Back to Vant Weapp

Field 输入框

packages/field/README.md

1.11.712.2 KB
Original Source

Field 输入框

介绍

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

引入

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

json
"usingComponents": {
  "van-field": "@vant/weapp/field/index"
}

代码演示

基础用法

html
<van-cell-group>
  <van-field
    value="{{ value }}"
    placeholder="请输入用户名"
    border="{{ false }}"
    bind:change="onChange"
  />
</van-cell-group>
js
Page({
  data: {
    value: '',
  },

  onChange(event) {
    // event.detail 为当前输入的值
    console.log(event.detail);
  },
});

双向绑定

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

html
<van-cell-group>
  <van-field
    model:value="{{ value }}"
    placeholder="请输入用户名"
    border="{{ false }}"
  />
</van-cell-group>
js
Page({
  data: {
    value: '',
  },
});

自定义类型

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

html
<van-cell-group>
  <van-field
    value="{{ username }}"
    required
    clearable
    label="用户名"
    icon="question-o"
    placeholder="请输入用户名"
    bind:click-icon="onClickIcon"
  />

  <van-field
    value="{{ password }}"
    type="password"
    label="密码"
    placeholder="请输入密码"
    required
    border="{{ false }}"
  />
</van-cell-group>

禁用输入框

html
<van-cell-group>
  <van-field
    value="输入框已禁用"
    label="用户名"
    left-icon="contact"
    disabled
    border="{{ false }}"
  />
</van-cell-group>

错误提示

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

html
<van-cell-group>
  <van-field
    value="{{ username }}"
    label="用户名"
    placeholder="请输入用户名"
    error
  />
  <van-field
    value="{{ phone }}"
    label="手机号"
    placeholder="请输入手机号"
    error-message="手机号格式错误"
    border="{{ false }}"
  />
</van-cell-group>

内容对齐方式

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

html
<van-cell-group>
  <van-field
    value="{{ username3 }}"
    label="用户名"
    placeholder="请输入用户名"
    input-align="right"
  />
</van-cell-group>

高度自适应

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

html
<van-cell-group>
  <van-field
    value="{{ message }}"
    label="留言"
    type="textarea"
    placeholder="请输入留言"
    autosize
    border="{{ false }}"
  />
</van-cell-group>

插入按钮

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

html
<van-cell-group>
  <van-field
    value="{{ sms }}"
    center
    clearable
    label="短信验证码"
    placeholder="请输入短信验证码"
    border="{{ false }}"
    use-button-slot
  >
    <van-button slot="button" size="small" type="primary">
      发送验证码
    </van-button>
  </van-field>
</van-cell-group>

替换输入框值

在微信小程序中,bind:input 事件可以通过返回字符串或者一个对象来替换输入框的值以及调整光标的位置,在 vant-weapp 中,可以通过调用 change 或 input 参数中的 callback 函数,传入参数来实现

html
<van-field
  value="{{ value }}"
  placeholder="请输入用户名"
  border="{{ false }}"
  clearable
  extra-event-params
  bind:change="onChange"
/>
js
Page({
  data: {
    value: '',
  },
  onChange(e) {
    const { value, callback } = e.detail;

    callback({
      value: value + 1,
      cursor: 0,
    });
  },
});

常见问题

真机上为什么会出现聚焦时 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 事件中取到输入的值。

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

如何扩大点击区域?点击 label、错误信息 都能聚焦唤起键盘呢?

升级至 1.10.21 版本及以上,配置 name 属性即可

API

Props

参数说明类型默认值
name在表单内提交时的标识符。可以通过配置 name 来扩大点击区域string-
label输入框左侧文本string-
size单元格大小,可选值为 largestring-
value当前输入的值string | number-
type可设置为任意原生类型, 如 number idcard textarea digit nicknamestringtext
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 },
单位为pxboolean | 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
extra-event-params v1.10.12开启事件增强模式,会在 input 和 change 事件额外提供 cursorkeyCode 参数,计划在下一个大版本作为默认行为booleanfalse

Events

事件说明回调参数
bind:input输入内容时触发event.detail: 当前输入值; 在 extra-event-params 为 true 时为 InputDetail
bind:change输入内容时触发event.detail: 当前输入值; 在 extra-event-params 为 true 时为 InputDetail
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 }
bind:nicknamereview v1.11.5用户昵称审核完毕后触发,仅在 type 为 "nickname" 时有效event.detail = { pass, timeout }

InputDetail

参数说明类型默认值
value当前输入值string-
cursor光标位置number-
keyCode键值number-
callback调用该函数传 { value: string, cursor: number } 来替换输入框的内容,具体用法可以参考 wx-inputfunction-

Slot

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

外部样式类

类名说明
custom-class v1.10.21根节点样式类
label-class左侧文本样式类
input-class输入框样式类
right-icon-class右侧图标样式类