虚拟输入框 <Experimental></Experimental> VirtualInput <Experimental></Experimental>

与 Input 输入框外观、用法一致。

安装

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。

与 Input 输入框外观、用法一致。

何时使用

需要配合虚拟键盘使用时。

示例

VirtualInput

属性

属性	说明	类型	默认值
clearable	是否启用清除图标，点击清除图标后会清空虚拟输入框	`boolean`	`false`
onBlur	失去焦点时触发	`() => void`	-
onClear	点击清除按钮时触发	`() => void`	-
onClick	点击时触发	`(e: React.MouseEvent<HTMLDivElement>) => void`	-
onFocus	获得焦点时触发	`() => void`	-
placeholder	提示文本	`string`	-
value	输入值	`string`	`''`
cursor	光标相关配置，movable 表示是否可调整，onMove 为光标移动回调	`{ movable?: boolean; onMove?: (position: number) => void }`	`{ movable: false }`

严格意义上讲，VirtualInput 并不是一个表单类型的组件，它只是对数据进行展示。

Ref

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

CSS 变量

属性	说明	默认值	全局变量
--caret-color	光标颜色	`var(--adm-color-primary)`	`--adm-virtual-input-caret-color`
--caret-width	光标宽度	`2px`	`--adm-virtual-input-caret-width`
--color	文字颜色	`var(--adm-color-text)`	-
--disabled-color	禁用状态下的文字颜色	`var(--adm-color-weak)`	-
--font-size	字号	`17px`	-
--placeholder-color	`placeholder` 文字颜色	`var(--adm-color-light)`	-
--text-align	文字对齐方式	`left`	-

与NumberKeyboard配合使用

强烈推荐将 NumberKeyboard 作为属性传入 VirtualInput，一方面可以少写很多联动代码，另外也有完善的无障碍支持。

如果两个组件分离式引入，则需手动添加联动逻辑代码，且存在无障碍支持问题。

// ✅ 推荐这么做
 <VirtualInput
  placeholder='请输入内容'
  clearable
  keyboard={
    <NumberKeyboard
      confirmText='确定'
      customKey={{ key: '.', title: '小数点' }}
    />
  }
/>

// ❌ 不推荐这么做
<VirtualInput
  placeholder='请输入内容'
  clearable
  value={value}
  onFocus={() => setVisible(true)}
  onBlur={() => setVisible(false)}
  onClear={() => setValue('')}
  ref={inputRef}
/>
<NumberKeyboard
  visible={visible}
  confirmText='确定'
  customKey={{ key: '.', title: '小数点' }}
  onInput={v => setValue(i => i + v)}
  onDelete={() => setValue(i => i.slice(0, i.length - 1))}
  onClose={() => { setVisible(false); inputRef.current?.blur(); }}
/>