Vant

繁體中文

简体中文
English

繁體中文

简体中文
English

Appearance

NumberKeyboard 数字键盘 - Vant 4

⌨️ NumberKeyboard 数字键盘 ​

🎯 介绍 ​

NumberKeyboard 组件提供虚拟数字键盘功能，可以配合密码输入框组件或自定义的输入框组件使用。让数字输入更加便捷！

📦 引入 ​

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

js
import { createApp } from'vue'; import { NumberKeyboard } from'vant'; const app = createApp(); app.use(NumberKeyboard);

🎯 代码演示 ​

🔧 默认样式 ​

最基础的数字键盘，就像手机上的拨号键盘一样简洁实用 📱

html
<template>
  <div>
    <van-cell is-link title="弹出默认键盘" @click="show = true" />
    <van-number-keyboard
      v-model:show="show"
      @input="onInput"
      @delete="onDelete"
      @blur="show = false"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const show = ref(false);

const onInput = (value) => {
  showToast(`输入了：${value} 🔢`);
};

const onDelete = () => {
  showToast('删除了一个字符 🗑️');
};
</script>

💡 小贴士：点击键盘以外的区域时，键盘会自动收起，通过阻止元素上的 touchstart 事件冒泡可以避免键盘收起。

💰 带右侧栏的键盘 ​

专为金额输入场景设计，右侧栏让操作更便捷 💳

html
<template>
  <div>
    <van-cell is-link title="弹出带右侧栏的键盘" @click="show = true" />
    <van-number-keyboard
      v-model:show="show"
      theme="custom"
      extra-key="."
      close-button-text="完成"
      @input="onInput"
      @delete="onDelete"
      @close="show = false"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const show = ref(false);

const onInput = (value) => {
  showToast(`输入金额：${value} 💰`);
};

const onDelete = () => {
  showToast('删除金额 💸');
};
</script>

🆔 身份证号键盘 ​

专为身份证号输入定制，X 键让最后一位输入无忧 🪪

html
<template>
  <div>
    <van-cell is-link title="身份证号键盘" @click="show = true" />
    <van-number-keyboard
      v-model:show="show"
      extra-key="X"
      close-button-text="完成"
      @input="onInput"
      @close="show = false"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const show = ref(false);

const onInput = (value) => {
  showToast(`身份证号：${value} 🆔`);
};
</script>

🏷️ 键盘标题 ​

给键盘加个标题，让用户知道在输入什么 📝

html
<template>
  <div>
    <van-cell is-link title="带标题的键盘" @click="show = true" />
    <van-number-keyboard
      v-model:show="show"
      title="请输入密码"
      extra-key="."
      close-button-text="完成"
      @close="show = false"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
</script>

🔧 配置多个按键 ​

双按键配置，让输入更灵活 ⚡

html
<template>
  <div>
    <van-cell is-link title="多按键配置" @click="show = true" />
    <van-number-keyboard
      v-model:show="show"
      theme="custom"
      :extra-key="['00', '.']"
      close-button-text="完成"
      @input="onInput"
      @close="show = false"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const show = ref(false);

const onInput = (value) => {
  showToast(`输入：${value} ⚡`);
};
</script>

🎲 随机数字键盘 ​

安全第一！随机排列的数字键盘，防止密码被偷窥 🔐

html
<template>
  <div>
    <van-cell is-link title="随机数字键盘" @click="show = true" />
    <van-number-keyboard
      v-model:show="show"
      :random-key-order="true"
      @input="onInput"
      @blur="show = false"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const show = ref(false);

const onInput = (value) => {
  showToast(`安全输入：${value} 🔐`);
};
</script>

🔗 双向绑定 ​

实时绑定输入值，就像魔法一样同步 ✨

html
<template>
  <div>
    <van-field
      v-model="value"
      readonly
      clickable
      label="输入值"
      placeholder="点击弹出键盘"
      @click="show = true"
    />
    <van-number-keyboard
      v-model="value"
      v-model:show="show"
      :maxlength="6"
      @blur="show = false"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
const value = ref('');
</script>

## API

### Props

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| v-model | 当前输入值，实时绑定用户输入 📝 | *string* | \- |
| show | 是否显示键盘，控制键盘的显示隐藏 👁️ | *boolean* | \- |
| title | 键盘标题，给键盘加个名字 🏷️ | *string* | \- |
| theme | 样式风格，可选值为 `custom`，决定键盘外观 🎨 | *string* | `default` |
| maxlength | 输入值最大长度，限制输入字符数 📏 | *number | string* | `Infinity` |
| transition | 是否开启过场动画，让键盘出现更优雅 ✨ | *boolean* | `true` |
| z-index | 键盘 z-index 层级，控制显示层次 📚 | *number | string* | `100` |
| extra-key | 底部额外按键的内容，自定义特殊按键 🔧 | *string | string\[\]* | `''` |
| close-button-text | 关闭按钮文字，空则不展示关闭按钮 ❌ | *string* | \- |
| delete-button-text | 删除按钮文字，空则展示删除图标 🗑️ | *string* | \- |
| close-button-loading | 是否将关闭按钮设置为加载中状态，仅在 `theme="custom"` 时有效 ⏳ | *boolean* | `false` |
| show-delete-key | 是否展示删除图标，控制删除键显示 🗑️ | *boolean* | `true` |
| blur-on-close | 是否在点击关闭按钮时触发 blur 事件 👆 | *boolean* | `true` |
| hide-on-click-outside | 是否在点击外部时收起键盘，点击空白处自动关闭 🖱️ | *boolean* | `true` |
| teleport | 指定挂载的节点，等同于 Teleport 组件的 [to 属性](https://cn.vuejs.org/api/built-in-components.html#teleport) 🎯 | *string | Element* | \- |
| safe-area-inset-bottom | 是否开启[底部安全区适配](./advanced-usage)，适配全面屏设备 📱 | *boolean* | `true` |
| random-key-order | 是否将通过随机顺序展示按键，增强安全性 🎲 | *boolean* | `false` |

### Events

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| input | 点击按键时触发，获取用户输入 ⌨️ | *key: string* |
| delete | 点击删除键时触发，执行删除操作 🗑️ | \- |
| close | 点击关闭按钮时触发，关闭键盘 ❌ | \- |
| blur | 点击关闭按钮或非键盘区域时触发，失去焦点 👆 | \- |
| show | 键盘完全弹出时触发，键盘显示时执行 👁️ | \- |
| hide | 键盘完全收起时触发，键盘隐藏时执行 🙈 | \- |

### Slots

| 名称 | 说明 |
| --- | --- |
| delete | 自定义删除按键内容，个性化删除键 🗑️ |
| extra-key | 自定义左下角按键内容，添加特殊功能键 🔧 |
| title-left | 自定义标题栏左侧内容，扩展标题区域 🏷️ |

### 类型定义

组件导出以下类型定义，让 TypeScript 开发更顺畅 📝

```ts
importtype { NumberKeyboardProps, NumberKeyboardTheme } from'vant';

NumberKeyboardTheme 的可选值如下：

ts
type NumberKeyboardTheme = 'default' | 'custom';

主题定制 ​

样式变量 ​

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件 🎨

名称默认值描述
--van-number-keyboard-backgroundvar(--van-gray-2)键盘背景色 🎨
--van-number-keyboard-key-height48px按键高度 📏
--van-number-keyboard-key-font-size28px按键字体大小 🔤
--van-number-keyboard-key-active-colorvar(--van-gray-3)按键激活颜色 ✨
--van-number-keyboard-key-backgroundvar(--van-white)按键背景色 🎨
--van-number-keyboard-delete-font-sizevar(--van-font-size-lg)删除键字体大小 🗑️
--van-number-keyboard-title-colorvar(--van-gray-7)标题文字颜色 🏷️
--van-number-keyboard-title-height34px标题栏高度 📏
--van-number-keyboard-title-font-sizevar(--van-font-size-lg)标题字体大小 🔤
--van-number-keyboard-close-padding0 var(--van-padding-md)关闭按钮内边距 📦
--van-number-keyboard-close-colorvar(--van-primary-color)关闭按钮颜色 ❌
--van-number-keyboard-close-font-sizevar(--van-font-size-md)关闭按钮字体大小 🔤
--van-number-keyboard-button-text-colorvar(--van-white)按钮文字颜色 ✏️
--van-number-keyboard-button-backgroundvar(--van-primary-color)按钮背景色 🎨
--van-number-keyboard-z-index100键盘层级 📚

常见问题 ​

在桌面端无法操作组件？ ​

参见桌面端适配 💻

相关文档 ​

基於Vant構建的企業級移動端解決方案

Copyright © 2025 siex.cn ｜ sitemap