NumberKeyboard 数字キーボード - Vant 4

⌨️ NumberKeyboard 数字キーボード

🎯 紹介

NumberKeyboard は仮想の数字キーボード機能を提供します。パスワード入力コンポーネントやカスタム入力コンポーネントと組み合わせて使用でき、数字入力をより便利にします。

📦 導入

以下の方法でコンポーネントをグローバル登録します。詳細はコンポーネント登録を参照してください。

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('1文字を削除しました 🗑️');
};
</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 と同等） 🎯 | *string | Element* | \- |
| safe-area-inset-bottom | 下部セーフエリア適応 📱 | *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 的可选值如下：

type NumberKeyboardTheme = 'default' | 'custom';

🎨 テーマカスタマイズ

🎛️ スタイル変数

コンポーネントは以下の CSS 変数を提供しており、カスタムスタイルに使用できます。使用方法については ConfigProvider コンポーネントを参照してください 🎨

名称	デフォルト値	説明
--van-number-keyboard-background	var(--van-gray-2)	キーボード背景色 🎨
--van-number-keyboard-key-height	48px	キーの高さ 📏
--van-number-keyboard-key-font-size	28px	キーのフォントサイズ 🔤
--van-number-keyboard-key-active-color	var(--van-gray-3)	キーのアクティブ色 ✨
--van-number-keyboard-key-background	var(--van-white)	キーの背景色 🎨
--van-number-keyboard-delete-font-size	var(--van-font-size-lg)	削除キーのフォントサイズ 🗑️
--van-number-keyboard-title-color	var(--van-gray-7)	タイトル文字色 🏷️
--van-number-keyboard-title-height	34px	タイトルバーの高さ 📏
--van-number-keyboard-title-font-size	var(--van-font-size-lg)	タイトル文字サイズ 🔤
--van-number-keyboard-close-padding	0 var(--van-padding-md)	閉じるボタンの内側余白 📦
--van-number-keyboard-close-color	var(--van-primary-color)	閉じるボタンの色 ❌
--van-number-keyboard-close-font-size	var(--van-font-size-md)	閉じるボタンの文字サイズ 🔤
--van-number-keyboard-button-text-color	var(--van-white)	ボタン文字色 ✏️
--van-number-keyboard-button-background	var(--van-primary-color)	ボタン背景色 🎨
--van-number-keyboard-z-index	100	キーボードのレイヤー 📚

よくある質問

デスクトップでコンポーネントを操作できない？

デスクトップ対応を参照してください 💻

📚 関連ドキュメント

PasswordInput パスワード入力 - パスワード入力向けコンポーネント 🔐
Field 入力欄 - 汎用入力コンポーネント 📝
Popup ポップアップ - ポップアップの基礎コンポーネント 📱
Overlay オーバーレイ - オーバーレイコンポーネント 🎭

⌨️ NumberKeyboard 数字キーボード ​

🎯 紹介 ​

📦 導入 ​

🎯 コード例 ​

🔧 デフォルトスタイル ​

💰 右側パネル付きキーボード ​

🆔 身分証番号キーボード ​

🏷️ キーボードタイトル ​

🔧 複数キーの設定 ​

🎲 ランダム数字キーボード ​

🔗 双方向バインディング ​

🎨 テーマカスタマイズ ​

🎛️ スタイル変数 ​

よくある質問 ​

デスクトップでコンポーネントを操作できない？ ​

📚 関連ドキュメント ​

⌨️ NumberKeyboard 数字キーボード

🎯 紹介

📦 導入

🎯 コード例

🔧 デフォルトスタイル

💰 右側パネル付きキーボード

🆔 身分証番号キーボード

🏷️ キーボードタイトル

🔧 複数キーの設定

🎲 ランダム数字キーボード

🔗 双方向バインディング

🎨 テーマカスタマイズ

🎛️ スタイル変数

よくある質問

デスクトップでコンポーネントを操作できない？

📚 関連ドキュメント