Stepper ステッパー - Vant 4
Stepper ステッパー
紹介
ステッパーは増加ボタン・減少ボタン・入力欄で構成され、一定範囲の数値を入力・調整するためのコンポーネントです。
導入
以下の方法でコンポーネントをグローバル登録します。詳細はコンポーネント登録を参照してください。
js
import { createApp } from'vue';
import { Stepper } from'vant';
const app = createApp();
app.use(Stepper);🎯 コード例
🔢 基本用法
v-model で入力値をバインドし、change イベントで値の変化を監視できます。数値の増減操作を簡単に実現します。
html
<template>
<van-stepper v-model="value" @change="onChange" />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(1);
const onChange = (value) => {
console.log('現在の値：', value);
};
return {
value,
onChange,
};
},
};
</script>📐 ステップ設定
step 属性で増減ボタンをクリックした際の変化量を設定します。デフォルトは 1 で、要件に応じて変更できます。
html
<template>
<van-stepper v-model="value" step="2" />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(1);
return {
value,
};
},
};
</script>📊 入力範囲の制限
min と max 属性で入力値の範囲を制限します。デフォルトでは範囲外の値は自動的に補正されますが、auto-fixed で自動補正を無効化できます。
html
<template>
<van-stepper v-model="value" min="5" max="40" />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(10);
return {
value,
};
},
};
</script>🔢 整数输入の制限
integer 属性を設定すると、入力欄は整数のみ入力可能になります。
html
<template>
<van-stepper v-model="value" integer />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(1);
return {
value,
};
},
};
</script>🚫 無効状態
disabled 属性でステッパーを無効化できます。無効状態ではボタンや入力欄の操作はできません。
html
<template>
<van-stepper v-model="value" disabled />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(1);
return {
value,
};
},
};
</script>🔒 入力欄の無効化
disable-input 属性で入力欄のみを無効化できます。ボタン操作のみ許可したい場合に適しています。
html
<template>
<van-stepper v-model="value" disable-input />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(1);
return {
value,
};
},
};
</script>📏 小数桁の固定
decimal-length 属性で小数の桁数を固定できます。数値フォーマットの一貫性を保ちます。
html
<template>
<van-stepper v-model="value" step="0.2" :decimal-length="1" />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(1.0);
return {
value,
};
},
};
</script>🎨 サイズのカスタマイズ
input-width 属性で入力欄の幅を、button-size 属性でボタンサイズおよび入力欄の高さを設定できます。
html
<template>
<van-stepper v-model="value" input-width="40px" button-size="32px" />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(1);
return {
value,
};
},
};
</script>⏳ 非同期変更
before-change 属性で値の変更前に検証・インターセプトできます。非同期処理に対応します。
html
<template>
<van-stepper v-model="value" :before-change="beforeChange" />
</template>
<script>
import { ref } from 'vue';
import { closeToast, showLoadingToast } from 'vant';
export default {
setup() {
const value = ref(1);
const beforeChange = (value) => {
showLoadingToast({ forbidClick: true });
return new Promise((resolve) => {
setTimeout(() => {
closeToast();
// resolve 関数で true または false を返します
resolve(true);
}, 500);
});
};
return {
value,
beforeChange,
};
},
};
</script>🔘 角丸スタイル
theme を round に設定すると角丸スタイルのステッパーを表示できます。よりモダンな見た目になります。
html
<template>
<van-stepper v-model="value" theme="round" button-size="22" disable-input />
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const value = ref(1);
return {
value,
};
},
};
</script>📋 API
🎛️ Props
| 属性名 | 説明 | 型 | デフォルト |
|---|---|---|---|
| v-model | 📊 現在の入力値 | *number | string* |
| min | 📉 最小値 | *number | string* |
| max | 📈 最大値 | *number | string* |
| auto-fixed | 🔧 制限範囲を超えた値を自動補正するか。false では自動補正しません | boolean | true |
| default-value | 🎯 初期値（v-model が空のときに適用） | *number | string* |
| step | 📐 ステップ（クリック毎の変化量） | *number | string* |
| name | 🏷️ 識別子。change イベントの引数で取得可能 | *number | string* |
| input-width | 📏 入力欄の幅（デフォルト単位は px） | *number | string* |
| button-size | 📐 ボタンサイズ・入力欄の高さ（デフォルト単位は px） | *number | string* |
| decimal-length | 📏 表示する小数桁数を固定 | *number | string* |
| theme | 🎨 スタイル。round を指定可能 | string | - |
| placeholder | 💬 入力欄のプレースホルダー | string | - |
| integer | 🔢 整数のみ入力を許可するか | boolean | false |
| disabled | 🚫 ステッパーを無効化するか | boolean | false |
| disable-plus | ➕ 増加ボタンを無効化するか | boolean | false |
| disable-minus | ➖ 減少ボタンを無効化するか | boolean | false |
| disable-input | 🔒 入力欄を無効化するか | boolean | false |
| before-change | ⏳ 値の変更前のコールバック。false で入力を阻止。Promise 返却可 | *(value: string) => boolean | Promise<boolean>* |
| show-plus | 👁️ 増加ボタンを表示するか | boolean | true |
| show-minus | 👁️ 減少ボタンを表示するか | boolean | true |
| show-input | 👁️ 入力欄を表示するか | boolean | true |
| long-press | 👆 長押しで増減を有効にするか | boolean | true |
| allow-empty | 🈳 空文字の入力を許可するか（true で許可） | boolean | false |
🎪 Events
| イベント名 | 説明 | コールバック引数 |
|---|---|---|
| change | 🔄 バインド値が変化したときに発火 | value: string, detail: { name: string } |
| overlimit | ⚠️ 無効なボタンをクリック時に発火 | - |
| plus | ➕ 増加ボタンをクリック時に発火 | - |
| minus | ➖ 減少ボタンをクリック時に発火 | - |
| focus | 🎯 入力欄がフォーカスしたときに発火 | event: Event |
| blur | 😴 入力欄がフォーカスを失ったときに発火 | event: Event |
📘 型定義
コンポーネントは以下の型定義をエクスポートし、TypeScript プロジェクトでの利用を容易にします：
ts
import type { StepperTheme, StepperProps } from 'vant';🎨 テーマカスタマイズ
🎭 スタイル変数
コンポーネントは以下の CSS 変数を提供しており、カスタムスタイルに使用できます。使用方法については ConfigProvider コンポーネント を参照してください。
| 名称 | デフォルト値 | 説明 |
|---|---|---|
| --van-stepper-background | var(--van-active-color) | 🎨 ステッパーの背景色 |
| --van-stepper-button-icon-color | var(--van-text-color) | 🔘 ボタンアイコンの色 |
| --van-stepper-button-disabled-color | var(--van-background) | 🚫 無効ボタンの背景色 |
| --van-stepper-button-disabled-icon-color | var(--van-gray-5) | 🚫 無効ボタンのアイコン色 |
| --van-stepper-button-round-theme-color | var(--van-primary-color) | 🔴 ラウンドテーマのボタン色 |
| --van-stepper-input-width | 32px | 📏 入力欄の幅 |
| --van-stepper-input-height | 28px | 📐 入力欄の高さ |
| --van-stepper-input-font-size | var(--van-font-size-md) | 🔤 入力欄の文字サイズ |
| --van-stepper-input-line-height | normal | 📏 入力欄の行の高さ |
| --van-stepper-input-text-color | var(--van-text-color) | 🖋️ 入力欄の文字色 |
| --van-stepper-input-disabled-text-color | var(--van-text-color-3) | 🚫 無効入力欄の文字色 |
| --van-stepper-input-disabled-background | var(--van-active-color) | 🚫 無効入力欄の背景色 |
| --van-stepper-radius | var(--van-radius-md) | 🔄 ステッパーの角丸サイズ |
よくある質問
なぜ value が string 型になることがある？
ユーザー入力の途中で小数点や空値（例：1.）が発生する場合があり、その際は文字列型が出力されます。
value を number 型に保ちたい場合は、v-model に number 修飾子を付与してください：
html
🔗 関連ドキュメント
📝 フォームコンポーネント
- Field 入力欄 - 📝 データ入力用の入力コンポーネント
- NumberKeyboard 数字キーボード - 🔢 仮想数字キーボード。パスワード入力などに最適
- Rate 評価 - ⭐ 対象を評価するためのコンポーネント
- Switch スイッチ - 🔄 オン・オフ状態の切り替え
📊 表示コンポーネント
- Progress 進捗バー - 📊 操作の進捗を表示
- Circle 円形進捗バー - ⭕ 円環状の進捗表示
- CountDown カウントダウン - ⏰ カウントダウンを表示
💬 フィードバックコンポーネント
- Toast トースト - 💬 画面中央に半透明の通知を表示
- Dialog ダイアログ - 📱 モーダルダイアログで案内や確認を提供
🛠️ ツールコンポーネント
- ConfigProvider グローバル設定 - ⚙️ Vant の全体設定（ダークモード・テーマカスタムなど）