# 密码输入框 <Experimental></Experimental> PasscodeInput <Experimental></Experimental>

- 页面: https://jiguang132.com/zh/resources/ant-design-mobile/docs/passcode-input
- 资源: Ant Design Mobile (https://jiguang132.com/zh/resources/ant-design-mobile.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design-mobile/docs.md

密码输入本文框。

## 安装

```bash
npm install antd-mobile@5.43.0
```

antd-mobile 是移动网页组件库，不是 React Native 或小程序组件。React 19 项目需在入口用 `unstableSetRender` 注册 `createRoot`，否则 Toast、Dialog 等命令式 API 无法渲染；深色模式通过 `<html data-prefers-color-scheme="dark">` 切换。

示例来自 Ant Design Mobile 官方仓库（MIT），固定在 npm 5.43.0 对应的提交；示例中的 `DemoBlock` 等展示辅助组件由 JGuang 重写，不属于 antd-mobile 的 API。

密码输入本文框。

## 何时使用

适用于输入密码时需要脱敏显示。

密码、验证码输入框

## 示例

## PasscodeInput

### 属性

| 属性 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| caret | 是否展示光标 | `boolean` | `true` |  |
| className | 外层 className | `string` | - |  |
| defaultValue | 非受控值 | `string` | - |  |
| direction | 输入框方向 | `'ltr' \| 'rtl'` | `'ltr'` |  |
| error | 是否有错 | `boolean` | `false` |  |
| keyboard | 键盘组件，如不传，默认使用系统原生的键盘 | `NumberKeyboard` | - |  |
| inputMode | 输入框类型, 改变原生键盘类型 | `'numeric' \| 'text'` | `'numeric'` | 5.39.0 |
| length | 输入框长度 | `number` | `6` |  |
| plain | 是否展示明文 | `boolean` | `false` |  |
| seperated | 格子是否是彼此分离的 | `boolean` | `false` |  |
| style | 外层 style | `CSSProperties` | - |  |
| value | 受控值 | `string` | - |  |
| onBlur | 失去焦点回调 | `() => void` | - |  |
| onChange | 输入时回调 | `(value: string) => void` | - |  |
| onFill | 填写完成回调 | `() => void` | - |  |
| onFocus | 获取焦点回调 | `() => void` | - |  |

当 `length` 为非正数时以默认值为准。

### Ref

| 属性  | 说明             | 类型         |
| ----- | ---------------- | ------------ |
| blur  | 让输入框失去焦点 | `() => void` |
| focus | 让输入框获得焦点 | `() => void` |

### CSS 变量

| 属性 | 说明 | 默认值 |
| --- | --- | --- |
| --border-color | 边框颜色 | `var(--adm-color-border)` |
| --border-radius | 边框圆角 | `8px` |
| --cell-gap | 单元格间距，仅在 `seperated` 模式下生效 | `6px` |
| --cell-size | 单元格大小 | `40px` |
| --dot-size | 密码隐藏时，点的大小 | `10px` |

## FAQ

### Q: PasscodeInput 在 iOS 上点击自动填充短信验证码，但格子内不显示数字？

这是 iOS 系统的兼容性限制导致的。在部分机型上，短信回填会直接写入原生 input 元素，但不触发 React 的 onChange 事件，导致组件状态无法同步。可以通过 ref 获取原生 input 元素，在 onFocus 或 onFill 回调中使用 setTimeout 手动同步 input.value。如果回填后需要调用 blur() 收起键盘，建议同样放在延迟逻辑中，确保状态渲染完成后再失焦。

```jsx
const inputRef = useRef(null);
const [value, setValue] = useState('');

const syncValue = () => {
  setTimeout(() => {
    // 获取原生 input 的值并同步
    const realValue = inputRef.current?.nativeElement?.value || inputRef.current?.value;
    if (realValue && realValue !== value) {
      setValue(realValue);
    }
  }, 100);
};

<PasscodeInput
  ref={inputRef}
  value={code}
  onChange={setCode}
  onFocus={handleFocus}
/>
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt