Field 输入框

介绍

用户可以在文本框内输入或编辑文字。

引入

app.jsonindex.json中引入组件,详细介绍见快速上手

  1. "usingComponents": {
  2. "van-field": "@vant/weapp/field/index"
  3. }

代码演示

基础用法

  1. <van-cell-group>
  2. <van-field
  3. value="{{ value }}"
  4. placeholder="请输入用户名"
  5. border="{{ false }}"
  6. bind:change="onChange"
  7. />
  8. </van-cell-group>
  1. Page({
  2. data: {
  3. value: '',
  4. },
  5. onChange(event) {
  6. // event.detail 为当前输入的值
  7. console.log(event.detail);
  8. },
  9. });

双向绑定

最低基础库版本在 2.9.3 以上时,可以使用简易双向绑定

  1. <van-cell-group>
  2. <van-field
  3. model:value="{{ value }}"
  4. placeholder="请输入用户名"
  5. border="{{ false }}"
  6. />
  7. </van-cell-group>
  1. Page({
  2. data: {
  3. value: '',
  4. },
  5. });

自定义类型

根据type属性定义不同类型的输入框。

  1. <van-cell-group>
  2. <van-field
  3. value="{{ username }}"
  4. required
  5. clearable
  6. label="用户名"
  7. icon="question-o"
  8. placeholder="请输入用户名"
  9. bind:click-icon="onClickIcon"
  10. />
  11. <van-field
  12. value="{{ password }}"
  13. type="password"
  14. label="密码"
  15. placeholder="请输入密码"
  16. required
  17. border="{{ false }}"
  18. />
  19. </van-cell-group>

禁用输入框

  1. <van-cell-group>
  2. <van-field
  3. value="输入框已禁用"
  4. label="用户名"
  5. left-icon="contact"
  6. disabled
  7. border="{{ false }}"
  8. />
  9. </van-cell-group>

错误提示

通过error或者error-message属性增加对应的错误提示。

  1. <van-cell-group>
  2. <van-field
  3. value="{{ username }}"
  4. label="用户名"
  5. placeholder="请输入用户名"
  6. error
  7. />
  8. <van-field
  9. value="{{ phone }}"
  10. label="手机号"
  11. placeholder="请输入手机号"
  12. error-message="手机号格式错误"
  13. border="{{ false }}"
  14. />
  15. </van-cell-group>

内容对齐方式

可以通过input-align属性设置内容的对齐方式。

  1. <van-cell-group>
  2. <van-field
  3. value="{{ username3 }}"
  4. label="用户名"
  5. placeholder="请输入用户名"
  6. input-align="right"
  7. />
  8. </van-cell-group>

高度自适应

对于 textarea,可以通过autosize属性设置高度自适应。

  1. <van-cell-group>
  2. <van-field
  3. value="{{ message }}"
  4. label="留言"
  5. type="textarea"
  6. placeholder="请输入留言"
  7. autosize
  8. border="{{ false }}"
  9. />
  10. </van-cell-group>

插入按钮

通过 button slot 可以在输入框尾部插入按钮。

  1. <van-cell-group>
  2. <van-field
  3. value="{{ sms }}"
  4. center
  5. clearable
  6. label="短信验证码"
  7. placeholder="请输入短信验证码"
  8. border="{{ false }}"
  9. use-button-slot
  10. >
  11. <van-button slot="button" size="small" type="primary">
  12. 发送验证码
  13. </van-button>
  14. </van-field>
  15. </van-cell-group>

常见问题

真机上为什么会出现聚焦时 placeholder 加粗、闪烁的现象?

由于微信小程序的 input 组件和 textarea 组件是原生组件,聚焦时会将原生的输入框覆盖在对应位置上,导致了这个现象的产生。

相关的讨论可以查看微信开放社区

真机上 placeholder 为什么会盖过 popup 等其它组件?

由于微信小程序的 input 组件和 textarea 组件是原生组件,遵循原生组件的限制,详情可以查看原生组件说明

textarea 的 placeholder 在真机上为什么会偏移?

微信小程序的 textarea 组件在 Android 和 iOS 中默认样式不同,在 iOS 中会有默认的 padding,且无法置 0。

同时 placeholder-stylevertical-alignline-height 等大量 css 属性都不生效。

这一系列的问题导致了 placeholder 在真机上可能会出现偏移。

微信已经在 2.10.0 基础库版本后支持移除默认的 padding,但低版本仍有问题。详情可以查看 微信开放社区

手写输入法为什么会丢失部分字符 / 手写输入法为什么不会触发 input 事件?

这是微信小程序的 input 组件本身的问题,如果需要兼容手写输入法的场景,可以在 blur 事件中取到输入的值。

相关的讨论可以查看微信开放社区

API

Props

参数说明类型默认值
name在表单内提交时的标识符string-
label输入框左侧文本string-
size单元格大小,可选值为 largestring-
value当前输入的值string | number-
type可设置为任意原生类型, 如 number idcard textarea digitstringtext
fixed如果 type 为 textarea 且在一个 position:fixed 的区域,需要显示指定属性 fixed 为 truebooleanfalse
focus获取焦点booleanfalse
border是否显示内边框booleantrue
disabled是否禁用输入框booleanfalse
readonly是否只读booleanfalse
clearable是否启用清除控件booleanfalse
clickable是否开启点击反馈booleanfalse
required是否显示表单必填星号booleanfalse
center是否使内容垂直居中booleanfalse
password是否是密码类型booleanfalse
title-width标题宽度string6.2em
maxlength最大输入长度,设置为 -1 的时候不限制最大长度number-1
placeholder输入框为空时占位符string-
placeholder-style指定 placeholder 的样式string-
custom-style自定义样式string-
is-link是否展示右侧箭头并开启点击反馈booleanfalse
arrow-direction箭头方向,可选值为 left up downstring-
show-word-limit是否显示字数统计,需要设置maxlength属性booleanfalse
error是否将输入内容标红booleanfalse
error-message底部错误提示文案,为空时不展示string‘’
error-message-align底部错误提示文案对齐方式,可选值为 center rightstring‘’
input-align输入框内容对齐方式,可选值为 center rightstringleft
autosize是否自适应内容高度,只对 textarea 有效,
可传入对象,如 { maxHeight: 100, minHeight: 50 },
单位为px
boolean | objectfalse
left-icon左侧图标名称或图片链接,可选值见 Icon 组件string-
right-icon右侧图标名称或图片链接,可选值见 Icon 组件string-
confirm-type设置键盘右下角按钮的文字,仅在 type=’text’ 时生效stringdone
confirm-hold点击键盘右下角按钮时是否保持键盘不收起,在 type=’textarea’ 时无效booleanfalse
hold-keyboardfocus 时,点击页面的时候不收起键盘booleanfalse
cursor-spacing输入框聚焦时底部与键盘的距离number50
adjust-position键盘弹起时,是否自动上推页面booleantrue
show-confirm-bar是否显示键盘上方带有”完成“按钮那一栏,只对 textarea 有效booleantrue
selection-start光标起始位置,自动聚集时有效,需与 selection-end 搭配使用number-1
selection-end光标结束位置,自动聚集时有效,需与 selection-start 搭配使用number-1
auto-focus自动聚焦,拉起键盘booleanfalse
disable-default-padding是否去掉 iOS 下的默认内边距,只对 textarea 有效booleantrue
cursor指定 focus 时的光标位置number-1
clear-trigger v1.8.4显示清除图标的时机,always 表示输入框不为空时展示,
focus 表示输入框聚焦且不为空时展示
stringfocus
always-embed v1.9.2强制 input 处于同层状态,默认 focus 时 input 会切到非同层状态 (仅在 iOS 下生效)booleanfalse

Events

事件说明回调参数
bind:input输入内容时触发event.detail: 当前输入值
bind:change输入内容时触发event.detail: 当前输入值
bind:confirm点击完成按钮时触发event.detail: 当前输入值
bind:click-icon点击尾部图标时触发-
bind:focus输入框聚焦时触发event.detail.value: 当前输入值;
event.detail.height: 键盘高度
bind:blur输入框失焦时触发event.detail.value: 当前输入值;
event.detail.cursor: 游标位置(如果 type 不为 textarea,值为 0)
bind:clear点击清空控件时触发-
bind:click-input点击输入区域时触发-
bind:linechange输入框行数变化时调用,只对 textarea 有效event.detail = { height: 0, heightRpx: 0, lineCount: 0 }
bind:keyboardheightchange键盘高度发生变化的时候触发此事件event.detail = { height: height, duration: duration }

Slot

名称说明
label自定义输入框标签,如果设置了label属性则不生效
left-icon自定义输入框头部图标
right-icon自定义输入框尾部图标
button自定义输入框尾部按钮
input自定义输入框,使用此插槽后,与输入框相关的属性和事件将失效

外部样式类

类名说明
label-class左侧文本样式类
input-class输入框样式类
right-icon-class右侧图标样式类

Field 输入框 - 图1