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'; importtype { 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 修饰符，就像给数据贴上"数字"标签一样：
デスクトップでクリアボタンをクリックしても効果がありませんか？
这是因为清除按钮是为移动端优化的，监听的是 Touch 事件而不是 Click 事件。如果你需要在桌面端使用，可以参考桌面端适配文档来解决这个问题！🖱️
🔗 関連文書
Field 输入框在实际项目中经常与这些组件搭配使用，它们就像一个和谐的大家庭，各司其职，共同打造完美的用户体验：
- Form 表单 - Field 的最佳搭档，提供表单验证、提交等完整功能
- Cell 单元格 - Field 的外衣，提供统一的列表样式
- CellGroup 单元格组 - 将多个 Field 组织在一起的容器
- Button 按钮 - 经常与 Field 配合，用于表单提交等操作
- Icon 图标 - 为 Field 添加各种图标装饰
- Popup 弹出层 - 可以在弹窗中使用 Field 进行信息输入
- Search 搜索 - 专门的搜索输入框，Field 的特化版本
- PasswordInput 密码输入框 - 另一种密码输入方式
- NumberKeyboard 数字键盘 - 可以与 Field 配合使用的自定义数字键盘
- DatePicker 日期选择 - 日期输入的专业选择
- Picker 选择器 - 选项选择的专业工具