InputOTP

InputOTP 从 HeroUI v2 到 v3 的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 InputOTP 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，InputOtp 根据 length prop 自动渲染插槽：

1import { InputOtp } from "@lenso/ui";2
3export default function App() {4  return <InputOtp length={4} />;5}

在 v3 中，InputOTP 改为复合组件，需要手动声明插槽：

1import { InputOTP } from "@lenso/ui";2
3export default function App() {4  return (5    <InputOTP maxLength={4}>6      <InputOTP.Group>7        <InputOTP.Slot index={0} />8        <InputOTP.Slot index={1} />9        <InputOTP.Slot index={2} />10        <InputOTP.Slot index={3} />11      </InputOTP.Group>12    </InputOTP>13  );14}

主要变化

1. 组件结构

v2： 单个组件，自动渲染各个分段
v3： 复合组件：InputOTP.Group、InputOTP.Slot、InputOTP.Separator

2. Prop 变更

v2 prop	v3 位置	说明
`length`	`InputOTP`	已重命名为 `maxLength`
`allowedKeys`	`InputOTP`	已重命名为 `pattern`（正则表达式）
`onValueChange`	`InputOTP`	改用 `onChange`
`description`、`errorMessage`	-	通过外部 Description / FieldError 处理
`variant`	`InputOTP`	简化为仅 `primary` \| `secondary`
`color`、`size`、`radius`	-	已移除（请改用 Tailwind CSS）
`classNames`	-	改在各子组件上使用 `className`
-	`textAlign`	新增 prop：插槽内的文本对齐（`'left'` \| `'center'` \| `'right'`）
-	`inputMode`	新增 prop：移动端的虚拟键盘类型（默认 `'numeric'`）
-	`placeholder`	新增 prop：空插槽的占位符文本
-	`pasteTransformer`	新增 prop：转换粘贴的文本（例如去掉连字符）

迁移示例

受控 InputOTP

1import { useState } from "react";2
3const [value, setValue] = useState("");4
5<InputOtp length={4} value={value} onValueChange={setValue} />

使用 allowedKeys / pattern

1<InputOtp allowedKeys="^[a-z]*$" length={4} />

表单校验

1{/* With description */}2<InputOtp description="Enter the code sent to your email" length={4} />3
4{/* With error message */}5<InputOtp errorMessage="Invalid code" isInvalid length={4} />

使用 onComplete 回调

1<InputOtp2  length={6}3  onComplete={(value) => console.log("Complete:", value)}4/>

组件结构

v3 InputOTP 遵循以下结构：

1InputOTP (Root)2  ├── InputOTP.Group3  │   ├── InputOTP.Slot (index={0})4  │   ├── InputOTP.Slot (index={1})5  │   └── ...6  ├── InputOTP.Separator (optional)7  └── InputOTP.Group (optional, for grouping)8      └── InputOTP.Slot (index={...})

v3 中的新增 prop

v3 引入了几个 v2 中没有的 prop：

textAlign：控制插槽内的文本对齐（'left' | 'center' | 'right'，默认 'left'）
inputMode：设置移动端虚拟键盘类型（'numeric' | 'text' | 'decimal' | 'tel' | 'search' | 'email' | 'url'，默认 'numeric'）
placeholder：设置空插槽的占位符文本
pasteTransformer：(text: string) => string 类型的函数，用于转换粘贴的文本（例如从粘贴的代码中移除连字符）

1<InputOTP2  maxLength={6}3  inputMode="numeric"4  textAlign="center"5  placeholder="-"6  pasteTransformer={(text) => text.replace(/-/g, "")}7>8  <InputOTP.Group>9    <InputOTP.Slot index={0} />10    <InputOTP.Slot index={1} />11    <InputOTP.Slot index={2} />12  </InputOTP.Group>13  <InputOTP.Separator />14  <InputOTP.Group>15    <InputOTP.Slot index={3} />16    <InputOTP.Slot index={4} />17    <InputOTP.Slot index={5} />18  </InputOTP.Group>19</InputOTP>

导出的正则表达式模式

为方便使用，HeroUI 从 input-otp 库再导出了几个常用的正则模式：

1import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS } from "@lenso/ui";2
3// Use with the pattern prop4<InputOTP pattern={REGEXP_ONLY_DIGITS} maxLength={6}>5  {/* ... */}6</InputOTP>

REGEXP_ONLY_DIGITS —— 仅限数字字符（0-9）
REGEXP_ONLY_CHARS —— 仅限字母字符（a-z、A-Z）
REGEXP_ONLY_DIGITS_AND_CHARS —— 字母数字字符（0-9、a-z、A-Z）

总结

组件结构：必须用 InputOTP.Group 与 InputOTP.Slot 手动声明插槽
length → maxLength：prop 重命名
allowedKeys → pattern：prop 重命名，改为接收正则表达式
onValueChange → onChange：事件处理函数重命名
移除 description：改用独立的 Description 组件
移除 errorMessage：改用独立的错误展示组件
简化变体：v3 仅支持 variant="primary" 与 variant="secondary"
移除 color：请用 Tailwind CSS 类设置样式
移除 size：请用 Tailwind CSS 类设置样式
移除 radius：请用 Tailwind CSS 类设置样式
移除 classNames：改在各子组件上使用 className prop
新增 prop：v3 新增了 textAlign、inputMode、placeholder 与 pasteTransformer
导出的正则模式：可使用 REGEXP_ONLY_DIGITS、REGEXP_ONLY_CHARS、REGEXP_ONLY_DIGITS_AND_CHARS 作为 pattern 的取值