For AI agents: the complete documentation index is available at /next/zh/llms.txt, the full documentation bundle is available at /next/zh/llms-full.txt, and this page is available as Markdown at /next/zh/ui/components/input-otp.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • InputOTP

    一个适用于 ReactLynx 的无样式、长度可配置的一次性密码(OTP)和 PIN 输入组件。`InputOTP` 通过一个隐藏的原生输入框统一管理键盘、焦点、删除、粘贴、过滤和值状态。使用者可以通过 `InputOTPSlot` 组合可见输入区域。
    Info

    你可以查看源码来了解它的运行原理,也欢迎大家提 PR 来丰富其能力。

    基础用法

    构建支持自动聚焦和完成回调的受控六位验证码输入框。

    示例

    功能演示

    了解输入类型、渲染函数、状态、掩码、分隔符和键盘避让能力。

    键盘感知

    让页面底部的验证码输入框在软键盘弹出后仍保持可见。

    RTL

    让验证码输入框继承外层布局的从右到左方向。

    结构

    <InputOTP length={slotCount}>
      {Array.from({ length: slotCount }, (_, index) => (
        <InputOTPSlot index={index} />
      ))}
    </InputOTP>

    组件 API

    InputOTP

    Props for InputOTP.

    autoFocusiOSAndroidHarmony
    类型boolean·默认值false
    挂载后自动聚焦隐藏输入框。
    classNameiOSAndroidHarmony
    类型string
    类名
    defaultValueiOSAndroidHarmony
    类型string
    非受控模式下的初始值。
    disablediOSAndroidHarmony
    类型boolean·默认值false
    禁用键盘输入和聚焦。
    inputTypeiOSAndroidHarmony
    类型InputOTPInputType·默认值"numeric"
    隐藏的原生输入框接受的字符集。
    invalidiOSAndroidHarmony
    类型boolean·默认值false
    通过渲染属性和 ui-invalid UI variant 暴露无效状态。
    lengthiOSAndroidHarmony
    类型number·默认值6
    OTP 或 PIN 字符数,必须为正整数。无效值会回退为 6。
    onBluriOSAndroidHarmony
    类型() => void
    隐藏输入框失焦时触发。
    onChangeiOSAndroidHarmony
    类型(value: string) => void
    规范化后的值变化时触发。
    onCompleteiOSAndroidHarmony
    类型(value: string) => void
    输入值从未完成变为完整时触发。
    onFocusiOSAndroidHarmony
    类型() => void
    隐藏输入框聚焦时触发。
    ref
    类型ForwardedRef<InputOTPRef>
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    valueiOSAndroidHarmony
    类型string
    受控值;不符合 inputType 的字符会被丢弃。
    childreniOSAndroidHarmony
    类型ReactNode | ((state: InputOTPRenderProps) => ReactNode)
    InputOTPSlot 子节点,或接收输入状态的渲染函数。InputOTP 不会自动创建输入槽。

    基于状态的样式与渲染

    该组件通过以下一种或两种方式暴露运行时状态。下表仅展示每个状态实际支持的方式:

    • UI variant class:支持时,对应组件节点会动态加上 ui-<state> 形式的类名,可用 .ui-<state> { ... } 选择器定制样式;
    • Render-prop 字段:支持时,当 children 传入函数,状态会以 children({ <state>: boolean, ... }) 的形式作为参数传入,便于在运行时做条件渲染。

    UI variants applied by InputOTP based on its render state.

    类名渲染属性类型说明
    ui-completecompleteboolean是否所有输入槽均已填充。 所有输入槽均已填充时应用于根节点。
    ui-disableddisabledboolean输入是否已禁用。 禁用输入时应用于根节点。
    ui-focusedfocusedboolean隐藏的原生输入框是否聚焦。 隐藏输入框聚焦时应用于根节点。
    ui-invalidinvalidboolean输入是否处于无效状态。 输入值无效时应用于根节点。

    InputOTPSlot

    Props for an individual InputOTP visual slot.

    classNameiOSAndroidHarmony
    类型string
    类名
    indexiOSAndroidHarmony
    类型number
    从零开始的索引,用于读取 InputOTP 中对应的字符。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    childreniOSAndroidHarmony
    类型ReactNode | ((state: InputOTPSlotRenderProps) => ReactNode)
    自定义输入槽内容。渲染函数会接收输入槽状态。省略时, InputOTPSlot 会渲染默认字符和可视光标。

    UI variants applied by InputOTPSlot based on its render state.

    类名渲染属性类型说明
    ui-completecompleteboolean当前输入框中的所有输入槽是否均已填充。 输入完成时应用于每个输入槽。
    ui-disableddisabledboolean输入是否已禁用。 禁用输入时应用于输入槽。
    ui-filledfilledboolean当前输入槽是否已经包含字符。 应用于已经包含字符的输入槽。
    ui-focusedfocusedboolean当前输入槽是否为包含可视光标的聚焦槽。 应用于包含可视光标的输入槽。
    ui-invalidinvalidboolean输入是否处于无效状态。 输入值无效时应用于输入槽。

    InputOTPRef

    Imperative methods exposed by InputOTP.

    bluriOSAndroidHarmony
    类型() => Promise<void>
    让隐藏的原生输入框失焦并收起键盘。
    cleariOSAndroidHarmony
    类型() => Promise<void>
    清空当前非受控值。在受控模式下,请通过 onChange 回调更新 value 属性。
    focusiOSAndroidHarmony
    类型() => Promise<void>
    聚焦隐藏的原生输入框并唤起配置的键盘。
    getValueiOSAndroidHarmony
    类型() => string
    返回当前展示的值。
    setValueiOSAndroidHarmony
    类型(value: string) => Promise<void>
    替换当前非受控值。在受控模式下,该方法通过 onChange 请求新值, value 属性仍是唯一数据源。不支持的字符会被丢弃。

    辅助类型

    InputOTPInputType

    InputOTPInputType
    类型alphabetic | numeric | alphanumeric
    InputOTP 接受的字符集。

    InputOTPLength

    InputOTPLength
    类型number
    InputOTP 管理的输入槽数量,必须为正整数。
    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。