华玥组件库

中文

English

中文

English

Appearance

Keyboard 键盘组件 ^0.7.0 ​

虚拟键盘组件，支持数字键盘、车牌号键盘、身份证键盘等多种模式，可自定义头部和按键。

📌平台差异说明 ​

APP(vue)H5微信小程序支付宝小程序
✔✔✔✔

2. v-model 绑定 ​

组件使用 v-model:show 控制显示，v-model 绑定输入值：

html
<hy-keyboard
    v-model:show="showKeyboard"   <!-- 控制显示/隐藏 -->
    v-model="inputValue"          <!-- 绑定输入的值 -->
    v-model:car-lang="carLang"    <!-- 在mode为car时候有效，切换中英文 -->
></hy-keyboard>

3. 车牌号键盘模式 ​

车牌号键盘支持两种模式：

模式属性说明使用场景
非受控模式传 auto-switch-lang组件内部自动管理语言切换简单场景，开箱即用
受控模式传 v-model:car-lang手动控制语言切换需要在父组件监听或控制语言

非受控模式示例：

html
<!-- 设置 auto-switch-lang 自动切换 -->
<hy-keyboard mode="car" v-model="value" auto-switch-lang></hy-keyboard>

受控模式示例：

html
<hy-keyboard
    mode="car"
    v-model="value"
    v-model:car-lang="carLang"
></hy-keyboard>
ts
const carLang = ref<'zh' | 'en'>('zh')

// 手动控制切换逻辑
const handleInput = (val: string) => {
    if (val.length === 1) {
        carLang.value = 'en'
    }
}

const handleDelete = () => {
    if (carControlledValue.value.length === 1) {
        carLang.value = 'zh'
    }
}

4. custom 模式说明 ​

custom 模式的键盘右侧有固定的侧边栏，包含删除键和关闭键：

  • 侧边栏的删除键和关闭键始终显示，不需要额外配置
  • 如果需要自定义额外按键位置，可以使用 extra-key 属性
html
<!-- custom 模式：底部有自定义键，右侧有固定删除和关闭键 -->
<hy-keyboard
    mode="custom"
    v-model="value"
    :extra-key="['00', '.']"
    close-text="完成"
></hy-keyboard>

5. extraKey 属性 ​

extraKey 支持两种格式：

html
<!-- 字符串：单个额外按键，显示在 0 左侧 -->
<hy-keyboard mode="custom" extra-key="+"></hy-keyboard>

<!-- 数组：多个额外按键 (custom模式有效) -->
<hy-keyboard mode="custom" :extra-key="['.', '00']"></hy-keyboard>

6. showDotKey 属性 ​

控制是否显示小数点键，默认显示：

html
<!-- 不显示小数点 -->
<hy-keyboard :show-dot-key="false"></hy-keyboard>

<!-- 显示小数点 (默认) -->
<hy-keyboard :show-dot-key="true"></hy-keyboard>

7. randomKeyOrder 属性 ​

设置为 true 后，数字按键顺序会随机打乱：

html
<hy-keyboard :random-key-order="true"></hy-keyboard>

注意

随机顺序只在键盘每次显示时生成一次，键盘打开期间点击按键不会改变其他按键位置。

8. close 事件处理 ​

点击关闭按钮或蒙层时，会触发 close 事件，但不会自动关闭键盘，需要手动处理：

html
<hy-keyboard
    v-model:show="showKeyboard"
    @close="showKeyboard = false"
></hy-keyboard>

9. 身份证键盘 ​

身份证键盘自动包含 X 键，建议配合 maxlength 使用：

html
<hy-keyboard mode="idcard" :maxlength="18"></hy-keyboard>

🏯基本使用示例 ​

默认数字键盘 ​

html
<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    close-text="完成"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>
ts
const showKeyboard = ref(false)
const value = ref('')

const handleInput = (val: string) => {
    console.log('输入:', val)
}

const handleDelete = () => {
    console.log('删除')
}

const handleClose = () => {
    console.log('关闭')
    showKeyboard.value = false
}

带右侧栏的键盘 ​

html
<hy-keyboard
    v-model:show="showKeyboard"
    v-model="value"
    mode="custom"
    close-text="完成"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>

身份证键盘 ​

html
<hy-keyboard
    v-model:show="showKeyboard"
    mode="idcard"
    v-model="value"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>

车牌号键盘(非受控模式) ​

html
<hy-keyboard
    v-model:show="showKeyboard"
    mode="car"
    auto-switch-lang="true"
    v-model="value"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>

车牌号键盘(受控模式) ​

html
<hy-keyboard
    v-model:show="showKeyboard"
    mode="car"
    v-model="value"
    v-model:car-lang="carLang"
    @input="handleInput"
    @delete="handleDelete"
    @close="handleClose"
></hy-keyboard>
ts
const carLang = ref<'zh' | 'en'>('zh')

const handleInput = (val: string) => {
    if (val.length === 1) {
        carLang.value = 'en'
    }
    console.log('车牌号输入:', val)
}

const handleDelete = () => {
    if (carControlledValue.value.length === 1) {
        carLang.value = 'zh'
    }
    console.log('车牌号删除:', carControlledValue.value)
}

⚙️键盘配置 ​

不显示小数点 ​

html
<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    :show-dot-key="false"
    close-text="完成"
></hy-keyboard>

自定义额外按键 ​

html
<!-- 单个额外按键 -->
<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    extra-key="+"
    close-text="完成"
></hy-keyboard>

<!-- 多个额外按键(custom模式) -->
<hy-keyboard
    v-model:show="showKeyboard"
    mode="custom"
    v-model="value"
    :extra-key="['00', '.']"
    close-text="完成"
></hy-keyboard>

随机数字键盘 ​

html
<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    :random-key-order="true"
    close-text="完成"
></hy-keyboard>

🏷️自定义头部 ​

带标题的键盘 ​

html
<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    title="标题"
    close-text="完成"
></hy-keyboard>

Slot自定义标题 ​

html
<hy-keyboard
    v-model:show="showKeyboard"
    mode="default"
    v-model="value"
    close-text="完成"
>
    <template #title>
        <view class="custom-title">
            <text class="custom-title-text">自定义标题</text>
        </view>
    </template>
</hy-keyboard>
scss
.custom-title {
    display: flex;
    align-items: center;
    justify-content: center;
    height: 100%;

    &-text {
        font-size: 32rpx;
        font-weight: 500;
        color: #333;
    }
}

API ​

Keyboard Props ​

参数说明类型默认值
show是否显示键盘booleanfalse
modelValue绑定的值string-
title标题string-
mode键盘模式，可选值：default(数字键盘)、custom(自定义键盘)、car(车牌号键盘)、idcard(身份证键盘)stringdefault
zIndex层级number100
maxlength最大输入长度numberInfinity
showDeleteKey是否显示删除键booleantrue
showDotKey是否显示小数点键booleantrue
randomKeyOrder是否随机键盘按键顺序booleanfalse
closeText确认按钮文本string-
deleteText删除按钮文本string-
closeButtonLoading关闭按钮是否显示加载状态booleanfalse
modal是否显示蒙层booleanfalse
hideOnClickOutside是否在点击外部时收起键盘booleantrue
lockScroll是否锁定滚动booleantrue
safeAreaInsetBottom是否在底部安全区域内booleantrue
extraKey额外按键，支持字符串或字符串数组string | string[]-
carLang车牌键盘语言模式，可选值：zh(省份)、en(字母)，不传则为非受控模式string-
autoSwitchLang车牌键盘是否自动切换语言booleanfalse
customStyle定义需要用到的外部样式CSSProperties-
customClass自定义外部类名string-

Keyboard Events ​

事件名说明回调参数
input输入内容时触发text: 输入的字符
delete删除内容时触发-
close关闭键盘时触发-
update:show可见状态改变时触发show: 当前可见状态
update:modelValue值改变时触发value: 当前值
update:carLang车牌语言改变时触发lang: 当前语言('zh'或'en')

Keyboard Slots ​

插槽名说明接收值
title自定义标题内容-
13:35