介绍

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

引入

在app.json或index.json中引入组件，详细介绍见快速上手

"usingComponents": {
  "mx-field": "/miniprogram_npm/m-ui/mx-field/index",
}

小程序码

可使用微信扫码查看小程序码

#

代码演示

基本用法

<mx-field value="{{ value }}" placeholder="请输入用户名" border="{{ false }}" bind:change="onChange"></mx-field>

Page({
  /**
   * 页面的初始数据
   */
  data: {
    title: '输入框',
    value: '', 
    password: '',
    phone: '123',
    img: '/assets/image/example/notice-bar/ic_warn_red@2x.png',
    mxIcon: 'mx-icon'
  },

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

双向绑定

<mx-field model:value="{{ value }}" placeholder="请输入用户名" border="{{ false }}"></mx-field>

自定义类型

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

<mx-field 
  value="{{ value }}" 
  type="password" 
  placeholder="请输入密码" 
  clearable 
  border="{{ false }}"
></mx-field>

禁用输入框

<mx-field value="输入框已禁用" placeholder="请输入密码" disabled border="{{ false }}"></mx-field>

错误提示

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

<mx-field value="{{ value }}" placeholder="错误提示" error></mx-field>
<mx-field value="{{ phone }}" error-message="手机号格式错误"></mx-field>

内容对齐方式

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

<mx-field value="{{ value }}" placeholder="请输入用户名" input-align="right"></mx-field>

高度自适应

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

<mx-field value="{{ value }}" type="textarea" placeholder="请输入留言" autosize></mx-field>

插入按钮

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

<mx-field value="{{ value }}" center placeholder="请输入短信验证码"  use-button-slot>
      <mx-button slot="button" size="small" type="primary">发送验证码</mx-button>
</mx-field>

常见问题

问：真机上为什么会出现聚焦时 placeholder 加粗、闪烁的现象？
答：由于微信小程序的 input 组件和 textarea 组件是原生组件，聚焦时会将原生的输入框覆盖在对应位置上，导致了这个现象的产生。

问：真机上 placeholder 为什么会盖过 popup 等其它组件？
答：由于微信小程序的 input 组件和 textarea 组件是原生组件，遵循原生组件的限制

问：textarea 的 placeholder 在真机上为什么会偏移？
答：微信小程序的 textarea 组件在 Android 和 iOS 中默认样式不同，在 iOS 中会有默认的 padding，且无法置 0。
同时 placeholder-style 对 vertical-align、line-height 等大量 css 属性都不生效。
这一系列的问题导致了 placeholder 在真机上可能会出现偏移。
微信已经在 2.10.0 基础库版本后支持移除默认的 padding，但低版本仍有问题。

问：手写输入法为什么会丢失部分字符 / 手写输入法为什么不会触发 input 事件？
答：这是微信小程序的 input 组件本身的问题，如果需要兼容手写输入法的场景，可以在 blur 事件中取到输入的值。

API

Props

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

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

名称	说明
left-icon	自定义输入框左侧图标
right-icon	自定义输入框右侧图标
button	自定义输入框尾部按钮
input	自定义输入框，使用此插槽后，与输入框相关的属性和事件将失效

外部样式类

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