Keyboard 虚拟键盘

介绍

虚拟键盘面板组件，支持英文、数字、带小数点数字、身份证、车牌号多种键盘类型。仅提供面板本体，弹层场景可搭配 Popup 使用。

基础用法

通过 type 设置键盘类型，默认为 english 英文键盘。面板顶部内置伪输入框展示当前输入值，可通过 v-model 绑定。

<vd-keyboard v-model="value" type="english" @confirm="onConfirm" />

输入框

面板顶部默认展示内置输入框：带闪动光标，无输入时底层展示占位文本。通过 show-input 隐藏，placeholder 自定义占位文本，input-align 设置文本对齐方式（默认居左），maxlength 限制输入长度（默认 -1 不限制）。

<vd-keyboard v-model="value" placeholder="请输入车牌号" :maxlength="8" />
<vd-keyboard v-model="value" :show-input="false" input-align="center" />

键盘类型

type 可选值为 english number decimal idcard plate：

值	说明
english	英文键盘（数字行 + A-Z，左下角为大写切换键）
number	数字键盘（0-9）
decimal	带小数点数字键盘（0-9 与 .）
idcard	身份证键盘（0-9 与 X）
plate	车牌号键盘（首字符限定省份，默认展示省份键盘，禁用 I O）

各类键盘的确认键均整行置于底部；英文类键盘（english plate 及省份面板）以半键为单位排布，切换键、删除键加宽，缺键的行两侧补空位居中；数字键盘末行仅剩 0 键时加宽至删除键左侧撑满。

<vd-keyboard type="decimal" />
<vd-keyboard type="idcard" />

大小写切换

英文键盘左下角默认展示 大写 切换键，点击后字母按键以小写展示并输入。

<vd-keyboard type="english" />

省份键盘

车牌号键盘首字符限定为省份，默认展示省份键盘（含使、领、警、学、港、澳）；输入省份后自动切换到字母键盘，可通过 ABC 键切回。第二位为发牌机关代号，仅允许字母，此时数字键自动禁用；普通车牌 7 位、新能源车牌 8 位，可通过 maxlength 控制。

<vd-keyboard v-model="value" type="plate" :maxlength="8" />

打乱按键顺序

开启 shuffle 后随机打乱普通按键的顺序，切换键与功能键（删除、确认）位置不受影响。通过 ref 调用暴露的 shuffle 方法可手动重新打乱。

<vd-keyboard type="number" shuffle />
<vd-keyboard ref="keyboardRef" type="number" shuffle />
<vd-button @click="keyboardRef.shuffle()">重排</vd-button>

自定义禁用按键

通过 disabled-keys 设置禁止点击的按键值列表，不区分大小写。

<vd-keyboard type="english" :disabled-keys="['I', 'O']" />

隐藏功能键

通过 show-delete、show-confirm 控制删除键、确认键的展示；delete-icon 传空字符串时删除键展示文字。删除键支持长按连续快速删除。

<vd-keyboard type="number" :show-confirm="false" />
<vd-keyboard type="number" delete-icon="" confirm-text="完成" />

搭配弹出层使用

面板本身不含弹层，可搭配 Popup 将键盘固定在页面底部。

<vd-cell title="车牌号输入" is-link @click="show = true" />

<vd-popup v-model="show" position="bottom" round closeable>
  <vd-keyboard v-model="value" type="plate" :maxlength="8" @confirm="show = false" />
</vd-popup>

API

Props

参数	说明	类型	默认值
model-value / v-model	键盘当前输入值	string	''
type	键盘类型，可选值为 english number decimal idcard plate	KeyboardType	'english'
show-input	是否展示顶部内置输入框	boolean	true
placeholder	输入框占位文本	string	语言包 -> keyboard.placeholder
input-align	输入框文本对齐方式，可选值为 left center right	KeyboardAlignType	'left'
maxlength	允许输入的最大长度，-1 表示不限制	number	-1
shuffle	是否打乱普通按键的顺序；切换键与功能键位置不受影响	boolean	false
disabled-keys	自定义禁用的按键值列表，不区分大小写	string[]	[]
show-delete	是否展示删除键	boolean	true
show-confirm	是否展示确认键	boolean	true
delete-icon	删除键图标，传空字符串时展示文字	string	'delete'
confirm-text	确认键文案	string	语言包 -> keyboard.confirmText

代替原始 Props

参数	说明	类型	默认值
custom-id	根节点 id	string	-
custom-class	根节点类名	ClassValue	-
custom-style	根节点样式	StyleValue	-

Events

事件名	说明	回调参数
update:model-value	输入值变化时触发	value: string 当前输入值
input	点击普通按键时触发	key: string 按键值
delete	点击删除键时触发，长按删除键可连续删除	-
confirm	点击确认键时触发	value: string 当前输入值

Slots

名称	说明
key	自定义按键内容，作用域参数为 item: KeyboardKey

Methods

通过 ref 可调用以下方法

方法名	说明	参数
shuffle	手动重新打乱当前面板的按键顺序；键盘类型、省份面板切换后面板重建，恢复按 shuffle 属性处理	-

类型定义

组件导出以下类型定义：

import type { KeyboardType, KeyboardKeyType, KeyboardSwitchType, KeyboardKey, KeyboardThemeVars } from 'vital-design';