用于输入一次性密码
基础用法
export function InputOtpBasic() { const [otp, setOtp] = useState("123"); return ( <div> <ElInputOtp value={otp} onChange={setOtp} /> <div style={valueText}>Value: {otp}</div> </div> );}
自定义长度
输入字段长度可以通过设置length属性来自定义。
export function InputOtpCustomLength() { const [otp1, setOtp1] = useState(""); const [otp2, setOtp2] = useState(""); return ( <div style={stack}> <ElInputOtp value={otp1} onChange={setOtp1} length={4} /> <ElInputOtp value={otp2} onChange={setOtp2} length={8} /> </div> );}
展示类型
有三种类型可用：outlined （默认）、filled 和 underlined。
export function InputOtpTypes() { const [otp1, setOtp1] = useState(""); const [otp2, setOtp2] = useState(""); const [otp3, setOtp3] = useState(""); return ( <div style={stack}> <div> <p style={label}>Outlined (Default)</p> <ElInputOtp value={otp1} onChange={setOtp1} type="outlined" /> </div> <div> <p style={label}>Filled</p> <ElInputOtp value={otp2} onChange={setOtp2} type="filled" /> </div> <div> <p style={label}>Underlined</p> <ElInputOtp value={otp3} onChange={setOtp3} type="underlined" /> </div> </div> );}
调整尺寸
有三个尺寸可用：large、default 和 small。
export function InputOtpSizes() { const [otp1, setOtp1] = useState(""); const [otp2, setOtp2] = useState(""); const [otp3, setOtp3] = useState(""); return ( <div style={stack}> <div> <p style={label}>Large</p> <ElInputOtp value={otp1} onChange={setOtp1} size="large" /> </div> <div> <p style={label}>Default</p> <ElInputOtp value={otp2} onChange={setOtp2} size="default" /> </div> <div> <p style={label}>Small</p> <ElInputOtp value={otp3} onChange={setOtp3} size="small" /> </div> </div> );}
禁用 & 只读
支持禁用和只读状态。
export function InputOtpDisabled() { const [otp1] = useState("123"); const [otp2] = useState("456"); return ( <div style={stack}> <div style={typeWrap}> <p style={label}>Disabled</p> <ElInputOtp value={otp1} disabled /> <ElInputOtp value={otp1} disabled type="filled" /> <ElInputOtp value={otp1} disabled type="underlined" /> </div> <div style={typeWrap}> <p style={label}>Readonly</p> <ElInputOtp value={otp2} readonly /> <ElInputOtp value={otp2} readonly type="filled" /> <ElInputOtp value={otp2} readonly type="underlined" /> </div> </div> );}
密码模式
使用 mask 属性来隐藏输入字符。
export function InputOtpMask() { const [otp, setOtp] = useState("123"); return ( <div> <ElInputOtp value={otp} onChange={setOtp} mask /> <div style={valueText}>Value: {otp}</div> </div> );}
分隔符
自定义OTP字段之间的分隔符。
export function InputOtpSeparator() { return ( <div style={stack}> <ElInputOtp separator="/" /> <ElInputOtp separator={(index) => (index & 1 ? "—" : "")} /> <ElInputOtp separatorSlot={() => "•"} /> </div> );}
自定义验证
设置 validator 属性以验证输入字符，并使用 inputmode 指定键盘类型。
export function InputOtpValidator() { const [otp1, setOtp1] = useState(""); const [otp2, setOtp2] = useState(""); const onlyAllowNumber = (value: string) => /^\d$/.test(value); const onlyAllowLetter = (value: string) => /^[a-zA-Z]$/.test(value); return ( <div style={stack}> <div> <p style={label}>Numbers only</p> <ElInputOtp value={otp1} onChange={setOtp1} validator={onlyAllowNumber} inputmode="numeric" /> </div> <div> <p style={label}>Letters only</p> <ElInputOtp value={otp2} onChange={setOtp2} validator={onlyAllowLetter} /> </div> </div> );}
Attributes
| 属性名 | 说明 | 类型 | 默认值 |
|---|
| value | OTP 各框的值。数字不能有前导零，官方仅允许初始化时传数字 | string / number | undefined |
| length | OTP 输入框数量 | number | 6 |
| validator | 自定义校验函数，返回 false 时该字符不写入 | Function | () => true |
| inputmode | 原生 inputmode 属性 | string | — |
| type | 输入框类型 | enum | outlined |
| size | 尺寸 | enum | — |
| mask | 是否密码模式（掩码显示） | boolean | — |
| disabled | 是否禁用 | boolean | undefined |
| readonly | 同原生 readonly | boolean | false |
| validate-event | 是否触发表单校验 | boolean | true |
| id | 原生 id 属性 | string | — |
| aria-label | 原生 aria-label 属性 | string | — |
| separator | 框之间的分隔符，字符串 / ReactNode / (index) => ReactNode | string / ReactNode / Function | — |
| class-name / style | 根元素类名与样式 | string / object | — |
Slots
| 插槽名 | 说明 | React 写法 |
|---|
| separator | 框之间的分隔符，作用域参数为当前框下标；提供即渲染 | separatorSlot={(index) => ReactNode} |
Events
| 事件名 | 说明 | 参数 |
|---|
| onChange | 值更新，对应官方 update:modelValue | Function |
| onValueChange | 失焦且值相比获焦时变化时触发，对应官方 change | Function |
| onFinish | 所有框填满时触发，对应官方 finish | Function |
| onFocus | 获焦时触发（跳过内部框之间的焦点转移） | Function |
| onBlur | 失焦时触发（跳过内部框之间的焦点转移） | Function |
Exposes
通过 ref 获取，对应官方 defineExpose。
| 名称 | 说明 | 类型 |
|---|
| inputRefs | HTML input 元素数组 | array |
| focus | 聚焦到指定 OTP 框 | Function |
| blur | 让当前聚焦的 OTP 框失焦 | Function |
