uView Pro X

简体中文

English

简体中文

English

主题

Keyboard 键盘 ​

17:06

说明 ​

底部弹出的自定义键盘，按 mode 内置数字（number）、身份证（card）、车牌号（car）三种布局。顶部工具条提供取消与确认按钮，确认/取消会先收起键盘再分别派发 confirm / cancel；支持点击遮罩关闭、底部安全区适配、按键随机打乱与工具条文案定制。

兼容性 ​

平台支持情况
App✅ 支持
H5✅ 支持
微信小程序✅ 支持

示例 ​

数字键盘 mode="number" ​

默认数字键盘，dot-enabled 控制小数点，点击按键触发 change，退格触发 backspace。

查看源码
vue
<template>
    <view class="keyboard-display">
        <text>{{ inputValue.length > 0 ? inputValue : '请点击按钮唤起键盘' }}</text>
    </view>
    <ux-button type="primary" shape="round" text="打开数字键盘" @click="open" />
    <ux-keyboard v-model="show" mode="number" @change="onChange" @backspace="onBackspace" @confirm="onConfirm" @cancel="onCancel" />
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();
const show = ref(false);
const inputValue = ref('');

const open = () => {
    show.value = true;
};

const keyToString = (key: string | number): string => {
    return typeof key == 'number' ? (key as number).toString() : key as string;
};

const onChange = (key: string | number) => {
    inputValue.value = inputValue.value + keyToString(key);
};

const onBackspace = () => {
    inputValue.value = inputValue.length > 0 ? inputValue.substring(0, inputValue.length - 1) : '';
};

const onConfirm = () => {
    toastRef.value?.show?.({ title: '输入完成：' + inputValue.value, type: 'success', duration: 2000 });
};

const onCancel = () => {
    toastRef.value?.show?.({ title: '已取消输入', type: 'info', duration: 2000 });
};
</script>

<style scoped>
.keyboard-display {
    display: flex;
    flex-direction: row;
    align-items: center;
    padding: 12px 15px;
    border-radius: 6px;
    background-color: #f8f8f8;
    margin-bottom: 12px;
}
</style>

身份证键盘 mode="card" ​

身份证键盘在数字键基础上增加 X 键，适合证件号码输入。

查看源码
vue
<template>
    <ux-button type="primary" shape="round" text="打开身份证键盘" @click="open" />
    <ux-keyboard v-model="show" mode="card" @change="onChange" @confirm="onConfirm" />
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();
const show = ref(false);
const inputValue = ref('');

const open = () => {
    show.value = true;
};

const onChange = (key: string | number) => {
    inputValue.value = inputValue.value + (typeof key == 'number' ? (key as number).toString() : key as string);
};

const onConfirm = () => {
    toastRef.value?.show?.({ title: '输入完成：' + inputValue.value, type: 'success', duration: 2000 });
};
</script>

车牌号键盘 mode="car" ​

车牌号键盘为省简称与字母数字混合布局，适合车牌输入。

查看源码
vue
<template>
    <ux-button type="primary" shape="round" text="打开车牌号键盘" @click="open" />
    <ux-keyboard v-model="show" mode="car" @change="onChange" @confirm="onConfirm" />
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();
const show = ref(false);
const inputValue = ref('');

const open = () => {
    show.value = true;
};

const onChange = (key: string | number) => {
    inputValue.value = inputValue.value + (typeof key == 'number' ? (key as number).toString() : key as string);
};

const onConfirm = () => {
    toastRef.value?.show?.({ title: '输入完成：' + inputValue.value, type: 'success', duration: 2000 });
};
</script>

定制文案与按键 ​

tips / cancel-text / confirm-text 定制工具条文案，random 打乱按键顺序。

查看源码
vue
<template>
    <ux-button type="warning" shape="round" text="打乱按键并定制文案" @click="open" />
    <ux-keyboard
        v-model="show"
        mode="number"
        :random="true"
        tips="安全输入"
        cancel-text="重输"
        confirm-text="确定"
        @change="onChange"
        @backspace="onBackspace"
        @confirm="onConfirm"
        @cancel="onCancel"
    />
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();
const show = ref(false);
const inputValue = ref('');

const open = () => {
    show.value = true;
};

const onChange = (key: string | number) => {
    inputValue.value = inputValue.value + (typeof key == 'number' ? (key as number).toString() : key as string);
};

const onBackspace = () => {
    inputValue.value = inputValue.length > 0 ? inputValue.substring(0, inputValue.length - 1) : '';
};

const onConfirm = () => {
    toastRef.value?.show?.({ title: '输入完成：' + inputValue.value, type: 'success', duration: 2000 });
};

const onCancel = () => {
    toastRef.value?.show?.({ title: '已取消输入', type: 'info', duration: 2000 });
};
</script>

工具条与遮罩开关 ​

tooltip 关闭整个工具条；show-tips / cancel-btn / confirm-btn 分别控制工具条元素；mask / mask-close-able / dot-enabled 控制遮罩与按键。

查看源码
vue
<template>
    <view class="keyboard-row">
        <ux-button custom-class="keyboard-item" type="success" size="small" shape="round" text="无工具条" @click="openBoard('noTooltip')" />
        <ux-button custom-class="keyboard-item" type="success" size="small" shape="round" text="隐藏提示与按钮" @click="openBoard('noTips')" />
        <ux-button custom-class="keyboard-item" type="success" size="small" shape="round" text="无遮罩无小数点" @click="openBoard('noMask')" />
    </view>
    <ux-keyboard
        v-model="show"
        mode="number"
        :tooltip="tooltip"
        :show-tips="showTips"
        :cancel-btn="cancelBtn"
        :confirm-btn="confirmBtn"
        :dot-enabled="dotEnabled"
        :mask="mask"
    />
</template>

<script setup lang="uts">
const show = ref(false);
const tooltip = ref(true);
const showTips = ref(true);
const cancelBtn = ref(true);
const confirmBtn = ref(true);
const dotEnabled = ref(true);
const mask = ref(true);

const openBoard = (kind: string) => {
    if (kind == 'noTooltip') {
        tooltip.value = false;
    } else if (kind == 'noTips') {
        showTips.value = false;
        cancelBtn.value = false;
        confirmBtn.value = false;
    } else {
        dotEnabled.value = false;
        mask.value = false;
    }
    show.value = true;
};
</script>

<style scoped>
.keyboard-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.keyboard-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

安全区与层级 ​

safe-area-inset-bottom 适配底部安全区，z-index 定制弹层层级。

查看源码
vue
<template>
    <ux-button type="info" shape="round" text="遮罩不可关 + 自定义层级" @click="open" />
    <ux-keyboard
        v-model="show"
        mode="number"
        :mask-close-able="false"
        :safe-area-inset-bottom="true"
        :z-index="9999"
    />
</template>

<script setup lang="uts">
const show = ref(false);

const open = () => {
    show.value = true;
};
</script>

API ​

Props ​

属性说明类型默认值版本
mode键盘类型，可选 number / card / car，默认 numberString'number'-
dotEnabled是否显示键盘的 "." 符号，默认 trueBooleantrue-
tooltip是否显示顶部工具条，默认 trueBooleantrue-
showTips是否显示工具条中间的提示，默认 trueBooleantrue-
tips工具条中间的提示文字，不传按模式取本地化默认文案String''-
cancelBtn是否显示工具条左边的「取消」按钮，默认 trueBooleantrue-
confirmBtn是否显示工具条右边的「完成」按钮，默认 trueBooleantrue-
random是否打乱键盘按键的顺序，默认 falseBooleanfalse-
safeAreaInsetBottom是否开启底部安全区适配，默认 trueBooleantrue-
maskCloseAble是否允许通过点击遮罩关闭键盘，默认 trueBooleantrue-
modelValue通过 v-model 控制键盘的弹出与收起，默认 falseBooleanfalse-
mask是否显示遮罩，默认 trueBooleantrue-
zIndex弹层 z-index，不传取全局 popup 层级String|Number--
cancelText取消按钮的文字，不传取本地化默认文案String''-
confirmText确认按钮的文字，不传取本地化默认文案String''-
customClass自定义根节点样式类String''-
customStyle自定义根节点样式Object|String--

Events ​

事件名说明回调参数版本
change点击按键时触发，携带按键内容value: string | number-
confirm点击工具条「完成」时触发--
cancel点击工具条「取消」时触发--
backspace点击退格键时触发；长按会连续触发--

Slots ​

插槽名说明版本
default工具条上方、弹层顶部的自定义内容-

注意事项 ​

  1. 点击「完成」或「取消」会先回写 modelValue=false 收起键盘，再派发对应事件；点击遮罩关闭只派发 update:modelValue，不会触发 cancel，需要区分关闭来源时请自行判断。
  2. dotEnabled 只影响 number / card 模式，car 模式由车牌键盘自行决定布局，该属性无效。
  3. 未传 tips / cancelText / confirmText 时按 mode 与当前语言取本地化文案，切换语言后会跟随更新；显式传值则固定不变。
  4. 默认插槽渲染在工具条之前，视觉上位于工具条上方，适合放标题或补充说明。
  5. zIndex 不传时取全局 popup 层级；遮罩关闭行为由 maskCloseAble 控制，mask=false 时既无遮罩也无法点击关闭。
  6. 长按退格连续触发由内层数字/车牌键盘实现，本组件只负责转发 backspace 事件。
Copyright © 2026 uView Pro X | 鲁ICP备2021040594号-5