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 原生属性，用于控制回车键样式，此 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 属性自动设置 |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| 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();Slots
| 名称 | 说明 | 参数 |
|---|---|---|
| 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 选择器 - 选项选择的专业工具