Field 入力フィールド - Vant 4
✏️ Field 入力フィールド
🎯 紹介
Field 入力フィールドは親切な記録係のようで、いつでもユーザーの考えや情報を受け取る準備ができています！📝 名前、パスワード、長文の文章など、どんなものでも優雅に受け入れ、さらに便利な機能 —— クリアボタン、フォーマット、文字数カウントなども提供します。
これは単なるテキストボックスではなく、ユーザーとアプリケーションの間のコミュニケーションの架け橋のようなものです。さまざまなタイプ設定によって、数字キーボード、パスワード入力ボックス、さらには複数行のテキストエディタに変身することができます。あらゆる入力を簡単で楽しいものにしましょう！✨
📦 導入
以下の方法でグローバルにコンポーネントを登録します。詳細な登録方法については、コンポーネントの登録を参照してください。
import { createApp } from'vue';
import { Field, CellGroup } from'vant';
const app = createApp();
app.use(Field);
app.use(CellGroup);🚀 コードデモ
🔧 基本的な使い方
最もシンプルな入力ボックスは白紙のようで、ユーザーがその上に素晴らしいものを書くのを待っています！v-model を使用して双方向バインディングを実現すると、リアルタイムのコミュニケーションチャネルが確立され、ユーザーが何を入力してもすぐにわかります。placeholder は優しいヒントの小精霊のようで、ユーザーに何を入力すべきかを教えてくれます。
import { ref } from'vue';
export default {
setup() {
const value = ref('');
return { value };
},
};🎭 カスタムタイプ
Field 入力フィールドは多面的な存在で、type 属性を通じて様々な専門的な役割に変身することができます：
- 📱 tel - 電話番号の専門家、数字キーボードを呼び出します
- 🔢 digit - 純粋な数字の守護者、数字の入力のみを許可します
- 🧮 number - 数学計算機、小数点とマイナス記号をサポートします
- 🔒 password - プライバシー保護者、入力内容を自動的に隠します
- 📝 text - 万能文字記録係（デフォルトの役割）
import { ref } from'vue';
export default {
setup() {
const tel = ref('');
const text = ref('');
const digit = ref('');
const number = ref('');
const password = ref('');
return { tel, text, digit, number, password };
},
};🚫 入力ボックスを無効にする
時々入力ボックスは「休憩」が必要です！readonly を使うと読み取り専用モードになり、美術館の展示品のように見ることはできますが触ることはできません。disabled を使うと完全に無効になり、閉店している店のように一時的に営業を停止します。
🎨 アイコンを表示
入力ボックスにアイコンを追加するのは、美しいアクセサリーを着せるようなものです！left-icon と right-icon を使用すると、両側にアイコンを配置でき、インターフェースがより直感的で美しくなります。また、clearable 属性を使用すると、ユーザーが入力する際に親切に小さなバツマークが表示され、一発で全ての内容をクリアできます。消しゴムのように便利です！
import { ref } from'vue';
export default {
setup() {
const value1 = ref('');
const value2 = ref('123');
return { value1, value2, };
},
};⭐ 必須アスタリスク
小さな赤いアスタリスクは優しいリマインダーのようで、ユーザーに「このフィールドは重要ですよ！」と伝えます。required 属性を使用すると、必須フィールドにこの可愛い小さな星を表示することができます。
⚠️ ヒント：required 属性はアスタリスクのスタイルを表示するだけで、実際のフォーム検証には rule.required と組み合わせる必要があります！
🤖 自動的にアスタリスクを表示
一つ一つアスタリスクを設定するのが面倒ですか？問題ありません！Form コンポーネントで required="auto" を設定すると、スマートモードがオンになり、すべての Field が検証ルールに基づいて自動的にアスタリスクを表示するかどうかを決定します。手間が省けて便利です！
❌ エラーメッセージ
ユーザーが誤った入力をした場合、Field は親切な先生に変身し、赤い枠とエラーメッセージで優しく問題を指摘します。error 属性を使用すると入力ボックスが赤くなり、error-message は下部に具体的なエラーメッセージを表示して、ユーザーが問題をすばやく見つけて解決できるように助けます。
🔘 ボタンを挿入
入力ボックスの横にボタンを置きたいですか？button スロットを使用すると実現できます！入力ボックスに有能なアシスタントを配置するようなもので、「送信」ボタン、「検索」ボタン、または必要などの操作ボタンにすることができます。
🎨 入力内容をフォーマット
時々ユーザーの入力内容は「美化」が必要です。例えば、自動的にスペースを追加したり、大文字小文字を変換したりするなどです。formatter 属性は親切なエディターのようで、ユーザーの入力内容をリアルタイムでフォーマットすることができます。format-trigger はいつフォーマットを実行するかを決定します —— 入力しながらフォーマットするのか、フォーカスを失ったときにフォーマットするのかです。
import { ref } from'vue';
export default {
setup() {
const value1 = ref('');
const value2 = ref('');
// 入力された数字を除去
const formatter = (value) => value.replace(/\d/g, '');
return { value1, value2, formatter, };
},
};📏 高さの自動調整
ユーザーが長い文章を入力する必要がある場合、固定高さのテキストボックスは少し窮屈に感じられます。autosize 属性を使用すると、textarea はスマートなゴムバンドのように、内容が増えるにつれて自動的に高さを伸ばし、ユーザーの文字に十分なスペースを提供します！
🔢 文字数カウントを表示
作文の文字数制限のように、時々ユーザーにまだどれだけ入力できるかを知らせる必要があります。maxlength と show-word-limit を設定すると、入力ボックスの下部に親切な文字数カウントが表示され、ユーザーは状況を把握できます！
📐 入力ボックスの内容の配置
異なるシーンでは異なる配置方法が必要です！input-align 属性を使用すると、入力内容を左揃え、中央揃え、または右揃えにすることができます。文書の配置を調整するのと同じくらい簡単です。
🏷️ 入力ボックスのテキスト位置
ラベルの位置も重要です！label-align 属性を使用すると、ラベルテキストを左揃え、中央揃え、右揃えにすることができます。さらに入力ボックスの上に配置することもでき、様々なデザインニーズに柔軟に対応できます。
API
Props
| パラメータ | 説明 | 型 | デフォルト値 |
|---|---|---|---|
| v-model | 現在の入力値 | *number | string* |
| label | 入力ボックスの左側のテキスト | string | - |
| name | 名前、フォーム送信時の識別子として使用 | string | - |
| id | 入力ボックスの id、label の for 属性も設定されます | string | van-field-n-input |
| type | 入力ボックスのタイプ、原生の input タグのすべての type 属性 をサポートし、さらに digit タイプも追加でサポートしています | FieldType | text |
| size | サイズ、オプションは large``normal | string | - | | maxlength | 入力できる最大文字数 | number | string | - | | min v4.9.5 | 入力ボックスのタイプが number または digit の場合に許可される最小値を設定 | number | - | | max v4.9.5 | 入力ボックスのタイプが number または digit の場合に許可される最大値を設定 | number | - | | placeholder | 入力ボックスのプレースホルダーテキスト | string | - | | border | 内側のボーダーを表示するかどうか | boolean | true | | disabled | 入力ボックスを無効にするかどうか | boolean | false | | readonly | 読み取り専用モードかどうか、読み取り専用モードでは内容を入力できません | boolean | false | | colon | label の後ろにコロンを追加するかどうか | boolean | false | | required | フォームの必須アスタリスクを表示するかどうか | boolean | 'auto' | null | | center | 内容を垂直方向に中央揃えにするかどうか | boolean | false | | clearable | クリアアイコンを有効にするかどうか、クリアアイコンをクリックすると入力ボックスが空になります | boolean | false | | clear-icon | クリアアイコンの名前または画像リンク、Icon コンポーネントの name 属性 と同等 | string | clear |
| clear-trigger | クリアアイコンを表示するタイミング、always は入力ボックスが空でない場合に表示、focus は入力ボックスがフォーカスされ、かつ空でない場合に表示 | FieldClearTrigger | focus | | clickable | クリックフィードバックを有効にするかどうか | boolean | false | | is-link | 右側の矢印を表示し、クリックフィードバックを有効にするかどうか | boolean | false | | autofocus | 自動的にフォーカスするかどうか、iOS システムはこの属性をサポートしていません | boolean | false | | show-word-limit | 文字数カウントを表示するかどうか、maxlength 属性の設定が必要 | boolean | false | | error | 入力内容を赤く表示するかどうか | boolean | false | | error-message | 下部のエラーメッセージ、空の場合は表示されません | string | - | | error-message-align | エラーメッセージの配置方法、オプションは center``right | FieldTextAlign | left | | formatter | 入力内容のフォーマット関数 | (val: string) => string | - | | format-trigger | フォーマット関数がトリガーされるタイミング、オプションは onBlur | FieldFormatTrigger | onChange | | arrow-direction | 矢印の方向、オプションは left``up``down | string | right | | label-class | 左側のテキストの追加クラス名 | string | Array | object | - | | label-width | 左側のテキストの幅、デフォルトの単位は px | number | string | 6.2em | | label-align | 左側のテキストの配置方法、オプションは center``right``top | FieldTextAlign | left | | input-align | 入力ボックスの配置方法、オプションは center``right | FieldTextAlign | left | | autosize | 内容の高さに自動的に合わせるかどうか、textarea にのみ有効、オブジェクトを渡すこともできます、例 { maxHeight: 100, minHeight: 50 }、単位はpx | boolean | FieldAutosizeConfig | false | | left-icon | 左側のアイコンの名前または画像リンク、Icon コンポーネントの name 属性 と同等 | string | - |
| right-icon | 右側のアイコンの名前または画像リンク、Icon コンポーネントの name 属性 と同等 | string | - |
| icon-prefix | アイコンのクラス名の接頭辞、Icon コンポーネントの class-prefix 属性 と同等 | string | van-icon |
| rules | フォーム検証ルール、詳細は Form コンポーネント を参照 | FieldRule[] | - |
| autocomplete | HTML 原生属性、自動補完機能を制御するために使用、詳細は MDN - autocomplete を参照 | string | - | | autocapitalize v4.6.2 | HTML 原生属性、テキスト入力時に自動的に大文字にするかどうかを制御、この API は一部のブラウザでのみサポートされています、詳細は MDN - autocapitalize を参照 | string | - | | enterkeyhint | HTML 原生属性、Enterキーのスタイルを制御するために使用、この API は一部のブラウザでのみサポートされています、詳細は MDN - enterkeyhint を参照 | string | - | | spellcheck v4.6.2 | HTML 原生属性、要素のスペルミスをチェックするために使用、この API は一部のブラウザでのみサポートされています、詳細は MDN - spellcheck を参照 | boolean | - | | autocorrect v4.6.2 | HTML 原生属性、Safari のみ適用、入力されたテキストを自動的に修正するために使用、詳細は MDN - autocorrect を参照 | string | - |
| inputmode v4.9.9 | HTML 原生属性、入力ボックスの入力モードを指定するために使用、詳細は MDN - inputmode を参照 | string | type 属性に基づいて自動的に設定 |
イベント
| イベント名 | 説明 | コールバックパラメータ |
|---|---|---|
| update:model-value | 入力内容が変化したときに発火 | value: string (現在の入力値) |
| focus | 入力欄がフォーカスしたときに発火 | event: Event |
| blur | 入力欄のフォーカスが外れたときに発火 | event: Event |
| clear | クリアボタンをクリックしたときにトリガーされます | event: MouseEvent |
| click | コンポーネントをクリックしたときにトリガーされます | event: MouseEvent |
| click-input | 入力エリアをクリックしたときにトリガーされます | event: MouseEvent |
| click-left-icon | 左側のアイコンをクリックしたときにトリガーされます | event: MouseEvent |
| click-right-icon | 右側のアイコンをクリックしたときにトリガーされます | event: MouseEvent |
| start-validate | フォームの検証を開始したときにトリガーされます | - |
| end-validate | フォームの検証が終了したときにトリガーされます | { status: string, message: string } |
メソッド
ref を通じて Field インスタンスを取得し、インスタンスメソッドを呼び出すことができます。詳細はコンポーネントのインスタンスメソッドを参照してください。
| メソッド名 | 説明 | パラメータ | 戻り値 |
|---|---|---|---|
| focus | 入力欄にフォーカスを当てる | - | - |
| blur | 入力ボックスのフォーカスを外す | - | - |
型定義
コンポーネントは以下の型定義をエクスポートします：
import type { FieldType, FieldRule, FieldProps, FieldInstance, FieldTextAlign, FieldRuleMessage, FieldClearTrigger, FieldFormatTrigger, FieldRuleValidator, FieldRuleFormatter, FieldValidateError, FieldAutosizeConfig, FieldValidateTrigger, FieldValidationStatus, } from'vant';FieldInstance はコンポーネントインスタンスの型です。使用例：
import { ref } from 'vue';
import type { FieldInstance } from 'vant';
const fieldRef = ref<FieldInstance>();
fieldRef.value?.focus();スロット
| 名前 | 説明 | パラメータ |
|---|---|---|
| label | 入力ボックスの左側テキストをカスタマイズ | - |
| input | 入力ボックスをカスタマイズ、このスロットを使用すると、入力ボックス関連の属性とイベントは無効になります | - |
| left-icon | 入力ボックスの左側のアイコンをカスタマイズ | - |
| right-icon | 入力ボックスの右側のアイコンをカスタマイズ | - |
| button | 入力ボックスの右側のボタンをカスタマイズ | - |
| error-message | 下部のエラーメッセージをカスタマイズ | { message: string } |
| extra | 入力ボックスの最も右側の追加コンテンツをカスタマイズ | - |
テーマのカスタマイズ
スタイル変数
コンポーネントは以下の CSS 変数を提供しており、スタイルのカスタマイズに使用できます。使用方法は ConfigProvider コンポーネント を参照してください。
| 名前 | デフォルト値 | 説明 |
|---|---|---|
| --van-field-label-width | 6.2em | - |
| --van-field-label-color | var(--van-text-color) | - |
| --van-field-label-margin-right | var(--van-padding-sm) | - |
| --van-field-input-text-color | var(--van-text-color) | - |
| --van-field-input-error-text-color | var(--van-danger-color) | - |
| --van-field-input-disabled-text-color | var(--van-text-color-3) | - |
| --van-field-placeholder-text-color | var(--van-text-color-3) | - |
| --van-field-icon-size | 18px | - |
| --van-field-clear-icon-size | 18px | - |
| --van-field-clear-icon-color | var(--van-gray-5) | - |
| --van-field-right-icon-color | var(--van-gray-6) | - |
| --van-field-error-message-color | var(--van-danger-color) | - |
| --van-field-error-message-font-size | 12px | - |
| --van-field-text-area-min-height | 60px | - |
| --van-field-word-limit-color | var(--van-gray-7) | - |
| --van-field-word-limit-font-size | var(--van-font-size-sm) | - |
| --van-field-word-limit-line-height | 16px | - |
| --van-field-disabled-text-color | var(--van-text-color-3) | - |
| --van-field-required-mark-color | var(--van-red) | - |
🤔 よくある質問
type を number に設定した後、なぜ input タグのタイプはまだ text ですか？
これはとても興味深いポイントです。HTML の原生 type="number" はモバイル環境で挙動が不安定で、iOS や Android では maxlength が効かない、入力値を正しく取得できないなどの問題が発生します。
より良いユーザー体験のために、Field コンポーネントではモダンブラウザがサポートする inputmode 属性 を用いてキーボード種別を制御しています。これにより数字キーボードを呼び出しつつ、原生 number 型の落とし穴を回避できます。
なぜ v-model でバインドされた値は string 型に更新されますか？
Field コンポーネントは内部処理の一貫性を保つため、すべての入力値を string 型に変換します。これにより不要な型変換の問題を避けられます。
数値型が必要な場合は、Vue が提供する .number 修飾子 を使用してください。
デスクトップでクリアボタンをクリックしても効果がありませんか？
クリアボタンはモバイル向けに最適化されており、Click ではなく Touch イベントを監視しています。デスクトップでの対応が必要な場合は、デスクトップ適応 を参照してください。
🔗 関連ドキュメント
Field は実際のプロジェクトで以下のコンポーネントと組み合わせて使われることが多く、役割分担しながら優れたユーザー体験を構築します：
- Form フォーム - バリデーションや送信などの機能を提供
- Cell セル - 一覧スタイルを提供する外観コンポーネント
- CellGroup セルグループ - 複数の Field をまとめるコンテナ
- Button ボタン - フォーム送信などでよく併用
- Icon アイコン - 各種アイコンを追加
- Popup ポップアップ - ポップアップ内での入力に使用
- Search 検索 - 専用の検索入力、Field の特化版
- PasswordInput パスワード入力 - 別のパスワード入力方式
- NumberKeyboard 数字キーボード - Field と組み合わせ可能なカスタム数字キーボード
- DatePicker 日付選択 - 日付入力のための選択コンポーネント
- Picker ピッカー - 選択肢を選ぶためのツール