# 表单组件

# 表单组件说明

组件 说明 最低版本
button 按钮 1.0.0
checkbox-group 多项选择器,内部由多个checkbox组成 1.0.0
checkbox 多选项目 1.0.0
form 表单,将组件内的用户输入的 <switch/> <input/> <checkbox/> <slider/> <radio/> <picker/>提交 1.0.0
input 输入框 1.0.0
label 用来改进表单组件的可用性,使用for属性找到对应的id,或者将控件放在该标签下,当点击时,就会触发对应的控件 1.0.0
picker 从底部弹起的滚动选择器,现支持三种选择器,通过mode来区分,分别是普通选择器,时间选择器,日期选择器,默认是普通选择器 1.0.0
picker-view 嵌入页面的滚动选择器 1.0.0
picker-view-column 滚动选择器子项 1.0.0
radio-group 单项选择器,内部由多个组成 1.0.0
radio 单选项目 1.0.0
slider 滑动选择器 1.0.0
switch 开关选择器 1.0.0
textarea 多行输入框 1.0.0
editor 富文本编辑器 2.5.2
keyboard-accessory 设置 input / textarea 聚焦时键盘上方 cover-view / cover-image 工具栏视图 2.11.6

# button

属性 类型 默认值 必填 说明 最低版本
size string default 按钮的大小 1.0.0
type string default 按钮的样式类型 1.0.0
plain boolean false 按钮是否镂空,背景色透明 1.0.0
disabled boolean false 是否禁用 1.0.0
loading boolean false 名称前是否带 loading 图标 1.0.0
form-type string 用于 form 组件,点击分别会触发 form 组件的 submit/reset 事件 1.0.0
open-type string 开放能力 2.12.11
hover-class string button-hover 指定按钮按下去的样式类。当 hover-class="none" 时,没有点击态效果 2.11.4
hover-stop-propagation boolean false 指定是否阻止本节点的祖先节点出现点击态 2.11.4
hover-start-time number 20 按住后多久出现点击态,单位毫秒 2.11.4
hover-stay-time number 70 手指松开后点击态保留时间,单位毫秒 2.11.4
lang string en 指定返回用户信息的语言,zh_CN 简体中文,zh_TW 繁体中文,en 英文。 不支持
session-from string 会话来源,open-type="contact"时有效 2.12.11
send-message-title string 当前标题 会话内消息卡片标题,open-type="contact"时有效 2.12.11
send-message-path 当前分享路径 default 会话内消息卡片点击跳转小程序路径,open-type="contact"时有效 2.12.11
send-message-img string 截图 会话内消息卡片图片,open-type="contact"时有效 2.12.11
app-parameter string 打开 APP 时,向 APP 传递的参数,open-type=launchApp时有效 2.12.11
show-message-card boolean false 是否显示会话内消息卡片,设置此参数为 true,用户进入客服会话会在右下角显示"可能要发送的小程序"提示,用户点击后可以快速发送小程序消息,open-type="contact"时有效 2.12.11
bindgetuserinfo eventhandle 用户点击该按钮时,会返回获取到的用户信息,回调的detail数据与ft.getUserInfo返回的一致,open-type="getUserInfo"时有效 2.12.11
bindcontact eventhandle 客服消息回调,open-type="contact"时有效 不支持
bindgetphonenumber eventhandle 获取用户手机号回调,open-type=getPhoneNumber时有效 2.12.11
binderror eventhandle 当使用开放能力时,发生错误的回调,open-type=launchApp时有效 2.12.11
bindopensetting eventhandle 在打开授权设置页后回调,open-type=openSetting时有效 2.12.11
bindlaunchapp eventhandle 打开 APP 成功的回调,open-type=launchApp时有效 2.12.11
bindchooseavatar eventhandle 打开 APP 成功的回调,open-type=launchApp时有效 2.12.11

# size 的合法值

说明 最低版本
default 默认大小
mini 小尺寸

# type 的合法值

说明 最低版本
primary 绿色
default 白色
warn 红色

# form-type 的合法值

说明 最低版本
submit 提交表单
reset 重置表单

# open-type 的合法值

说明 最低版本
contact 打开客户会话 2.12.11
share 触发用户转发 2.12.11
getPhoneNumber 获取用户手机号,可以在 bindgetphonenumber 回调中获取到用户信息 2.12.11
getUserInfo 获取用户信息,可以在 bindgetuserinfo 回调中获取到用户信息 2.12.11
launchApp 打开APP,可以通过 app-parameter 属性设定向APP传的参数 2.12.11
openSetting 打开授权设置页 2.12.11
feedback 打开意见反馈页面 2.12.11
chooseAvatar 获取用户头像,可以在 bindchooseavatar 回调中获取到头像信息 2.12.11

需要注意的是,contact、getPhoneNumber、feedback、chooseAvatar 等功能不会在 SDK 中实现,调用上述功能时,参数会透传到 APP,需要 APP 自行实现相关功能,具体可参考 APP 的文档:

ios

android

# lang 的合法值

说明 最低版本
en 英文
zh_CN 简体中文
zh_TW 繁体中文

# checkbox

属性 类型 默认值 必填 说明 最低版本
color string #09BB07 checkbox的颜色,同css的color 1.0.0
value string checkbox标识,选中时触发checkbox-group的 change 事件,并携带 checkbox 的 value 2.11.4
disabled boolean false 是否禁用 2.11.4
checked boolean false 当前是否选中,可用来设置默认选中 2.11.4

# checkbox-group

属性 类型 默认值 必填 说明 最低版本
bindchange EventHandle checkbox-group中选中项发生改变时触发 change 事件,detail = {value:[选中的checkbox的value的数组]} 2.11.4

# editor

属性 类型 默认值 必填 说明 最低版本
read-only boolean false 设置编辑器为只读 2.7.0
placeholder string 提示信息 2.7.0
show-img-size boolean false 点击图片时显示图片大小控件 2.7.0
show-img-toolbar boolean false 点击图片时显示工具栏控件 2.7.0
show-img-resize boolean false 点击图片时显示修改尺寸控件 2.7.0
bindready eventhandle 编辑器初始化完成时触发 2.7.0
bindfocus eventhandle 编辑器聚焦时触发,event.detail = {html, text, delta} 2.7.0
bindblur eventhandle 编辑器失去焦点时触发,detail = {html, text, delta} 2.7.0
bindinput eventhandle 编辑器内容改变时触发,detail = {html, text, delta} 2.7.0
bindstatuschange eventhandle 通过 Context 方法改变编辑器内样式时触发,返回选区已设置的样式 2.7.0

# form

属性 类型 默认值 必填 说明 最低版本
report-submit boolean false 是否返回 formId 用于发送模板消息 1.0.0
bindsubmit eventhandle 携带 form 中的数据触发 submit 事件,event.detail = {value : {'name': 'value'} , formId: ''} 1.0.0
bindreset eventhandle 表单重置时会触发 reset 事件 1.0.0
report-submit-timeout number 0 等待一段时间(毫秒数)以确认 formId 是否生效。如果未指定这个参数,formId 有很小的概率是无效的(如遇到网络失败的情况)。指定这个参数将可以检测 formId 是否有效,以这个参数的时间作为这项检测的超时时间。如果失败,将返回 requestFormId:fail 开头的 formId 不支持

# label

属性 类型 默认值 必填 说明 最低版本
for string 绑定控件的 id 1.0.0

# picker

属性 类型 默认值 必填 说明 最低版本
mode string selector 选择器类型 1.0.0
disabled boolean false 是否禁用 1.0.0
confirm-color string #586c94 确认按钮文字颜色 1.0.0
cancel-color string #586c94 取消按钮文字颜色 1.0.0
bindcancel eventhandle 取消选择时触发
header-text string 选择器的标题,仅Android可用 不支持

# mode 的合法值

说明 最低版本
selector 普通选择器
multiSelector 多列选择器
time 时间选择器
date 日期选择器
region 省市区选择器

除了上述通用的属性,对于不同的mode,picker拥有不同的属性。

# 多列选择器:mode = multiSelector

属性 类型 默认值 必填 说明 最低版本
range array/object array [] mode 为 selector 或 multiSelector 时,range 有效
range-key string mode 为 selector 或 multiSelector 时,range 有效
value array [] 表示选择了 range 中的第几个(下标从 0 开始)
bindchange eventhandle value 改变时触发 change 事件,event.detail = {value}
bindcolumnchange eventhandle 列改变时触发

# 多列选择器:mode = time

属性 类型 默认值 必填 说明 最低版本
value string 表示选中的时间,格式为"hh:mm"
start string 表示有效时间范围的开始,字符串格式为"hh:mm"
end string 表示有效时间范围的结束,字符串格式为"hh:mm"
bindchange eventhandle value 改变时触发 change 事件,event.detail = {value}

# 多列选择器:mode = date

属性 类型 默认值 必填 说明 最低版本
value string 当天 表示选中的日期,格式为"YYYY-MM-DD"
start string 表示有效日期范围的开始,字符串格式为"YYYY-MM-DD"
end string 表示有效日期范围的结束,字符串格式为"YYYY-MM-DD"
fields string day 有效值 year,month,day,表示选择器的粒度
bindchange eventhandle value 改变时触发 change 事件,event.detail = {value}

# fields 有效值:*

说明 最低版本
year 选择器粒度为年
month 选择器粒度为月份
day 选择器粒度为天

# 多列选择器:mode = region

属性 类型 默认值 必填 说明 最低版本
value array [] 表示选中的省市区,默认选中每一列的第一个值
custom-item string 可为每一列的顶部添加一个自定义的项
level string region 选择器层级
bindchange eventhandle value 改变时触发 change 事件,event.detail = {value, code, postcode},其中字段 code 是统计用区划代码,postcode 是邮政编码

# picker-view

属性 类型 默认值 必填 说明 最低版本
value Array 数组中的数字依次表示 picker-view 内的 picker-view-column 选择的第几项(下标从 0 开始),数字大于 picker-view-column 可选项长度时,选择最后一项。 1.0.0
indicator-style string 设置选择器中间选中框的样式 1.0.0
indicator-class string 设置选择器中间选中框的类名 2.11.4
immediate-change boolean false 是否在手指松开时立即触发 change 事件。若不开启则会在滚动动画结束后触发 change 事件。 不支持
mask-style string 设置蒙层的样式 2.11.4
mask-class string 设置蒙层的类名 2.11.4
bindchange eventhandle 滚动选择时触发change事件,event.detail = {value};value为数组,表示 picker-view 内的 picker-view-column 当前选择的是第几项(下标从 0 开始) 2.11.4
bindpickstart eventhandle 当滚动选择开始时候触发事件 2.11.4
bindpickend eventhandle 当滚动选择结束时候触发事件 2.11.4

# picker-view-column

滚动选择器子项。仅可放置于picker-view中,其孩子节点的高度会自动设置成与picker-view的选中框的高度一致

# radio

属性 类型 默认值 必填 说明 最低版本
color string #09BB07 radio的颜色,同css的color 1.0.0
value string radio 标识。当该radio 选中时,radio-group 的 change 事件会携带radio的value 2.11.4
checked boolean false 当前是否选中 2.11.4
disabled boolean false 是否禁用 2.11.4

# radio-group

属性 类型 默认值 必填 说明 最低版本
bindchange EventHandle radio-group中选中项发生改变时触发 change 事件,detail = {value:[选中的radio的value的数组]} 2.11.4

# slider

属性 类型 默认值 必填 说明 最低版本
min number 0 最小值 1.0.0
max number 100 最大值 1.0.0
step number 1 步长,取值必须大于 0,并且可被(max - min)整除 1.0.0
disabled boolean false 是否禁用 1.0.0
value number 0 当前取值 1.0.0
color color #e9e9e9 背景条的颜色(请使用 backgroundColor) 1.0.0
selected-color color #1aad19 已选择的颜色(请使用 activeColor) 1.0.0
show-value boolean false 是否显示当前 value 1.0.0
bindchange eventhandle 完成一次拖动后触发的事件,event.detail = {value} 1.0.0
activeColor color #1aad19 已选择的颜色 2.11.4
backgroundColor color #e9e9e9 背景条的颜色 2.11.4
block-size number 28 滑块的大小,取值范围为 12 - 28 2.11.4
block-color color #ffffff 滑块的颜色 2.11.4
bindchanging eventhandle 拖动过程中触发的事件,event.detail = {value} 2.11.4

# switch

属性 类型 默认值 必填 说明 最低版本
checked boolean false 是否选中 1.0.0
disabled boolean false 是否禁用 1.0.0
type string switch 样式,有效值:switch, checkbox 1.0.0
color string #04BE02 switch 的颜色,同 css 的 color 1.0.0
bindchange eventhandle checked 改变时触发 change 事件,event.detail={ value} 1.0.0

# input

属性 类型 默认值 必填 说明 最低版本
value string 输入框的初始内容 2.11.4
type string text input 的类型 2.11.4
password boolean false 是否是密码类型 2.11.4
placeholder string 输入框为空时占位符 2.11.4
placeholder-style string 指定 placeholder 的样式 2.11.4
placeholder-class string input-placeholder 指定 placeholder 的样式类 2.11.4
disabled boolean false 是否禁用 2.11.4
maxlength number 140 最大输入长度,设置为 -1 的时候不限制最大长度 2.11.4
cursor-spacing number 0 指定光标与键盘的距离,取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离
auto-focus boolean false (即将废弃,请直接使用 focus )自动聚焦,拉起键盘
focus boolean false 获取焦点
confirm-type string done 设置键盘右下角按钮的文字,仅在type='text'时生效
cursor number 指定focus时的光标位置
confirm-hold boolean false 点击键盘右下角按钮时是否保持键盘不收起
selection-start number -1 光标起始位置,自动聚集时有效,需与selection-end搭配使用
selection-end number -1 光标结束位置,自动聚集时有效,需与selection-start搭配使用
adjust-position boolean true 键盘弹起时,是否自动上推页面
bindinput eventhandle 键盘输入时触发,event.detail = {value, cursor, keyCode},keyCode 为键值,2.1.0 起支持,处理函数可以直接 return 一个字符串,将替换输入框的内容。
bindfocus eventhandle 输入框聚焦时触发,event.detail = { value, height },height 为键盘高度
bindblur eventhandle 输入框失去焦点时触发,event.detail = {value: value}
bindconfirm eventhandle 点击完成按钮时触发,event.detail = {value: value}
bindkeyboardheightchange eventhandle 键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration}
always-embed boolean false 强制 input 处于同层状态,默认 focus 时 input 会切到非同层状态 (仅在 iOS 下生效) 不支持
hold-keyboard boolean false focus时,点击页面的时候不收起键盘
safe-password-cert-path string 安全键盘加密公钥的路径,只支持包内路径 不支持
safe-password-length number 安全键盘输入密码长度 不支持
safe-password-time-stamp number 安全键盘加密时间戳 不支持
safe-password-nonce string 安全键盘加密盐值 不支持
safe-password-salt string 安全键盘计算hash盐值,若指定custom-hash 则无效 不支持
safe-password-custom-hash string 安全键盘计算hash的算法表达式,如 md5(sha1('foo' + sha256(sm3(password + 'bar')))) 不支持

# type 的合法值

说明 最低版本
text 文本输入键盘
number 数字输入键盘
idcard 身份证输入键盘
digit 带小数点的数字键盘

# confirm-type 的合法值

说明 最低版本
send 右下角按钮为“发送”
search 右下角按钮为“搜索”
next 右下角按钮为“下一个”
go 右下角按钮为“前往”
done 右下角按钮为“完成”

# textarea

属性 类型 默认值 必填 说明 最低版本
value string 输入框的内容
placeholder string 输入框为空时占位符
placeholder-style string 指定 placeholder 的样式,目前仅支持color,font-size和font-weight
placeholder-class string textarea-placeholder 指定 placeholder 的样式类
disabled boolean false 是否禁用
maxlength number 140 最大输入长度,设置为 -1 的时候不限制最大长度
auto-focus boolean false 自动聚焦,拉起键盘。
focus boolean false 获取焦点
auto-height boolean false 是否自动增高,设置auto-height时,style.height不生效
fixed boolean false 如果 textarea 是在一个 position:fixed 的区域,需要显示指定属性 fixed 为 true
cursor-spacing number 0 指定光标与键盘的距离。取textarea距离底部的距离和cursor-spacing指定的距离的最小值作为光标与键盘的距离
cursor number -1 指定focus时的光标位置
show-confirm-bar boolean true 是否显示键盘上方带有”完成“按钮那一栏
selection-start number -1 光标起始位置,自动聚集时有效,需与selection-end搭配使用
selection-end number -1 光标结束位置,自动聚集时有效,需与selection-start搭配使用
adjust-position boolean true 键盘弹起时,是否自动上推页面
hold-keyboard boolean false focus时,点击页面的时候不收起键盘
disable-default-padding boolean false 是否去掉 iOS 下的默认内边距
bindfocus eventhandle 输入框聚焦时触发,event.detail = { value, height },height 为键盘高度,在基础库 1.9.90 起支持
bindblur eventhandle 输入框失去焦点时触发,event.detail = {value, cursor}
bindlinechange eventhandle 输入框行数变化时调用,event.detail = {height: 0, heightRpx: 0, lineCount: 0}
bindinput eventhandle 当键盘输入时,触发 input 事件,event.detail = {value, cursor, keyCode},keyCode 为键值,目前工具还不支持返回keyCode参数。bindinput 处理函数的返回值并不会反映到 textarea 上
bindconfirm eventhandle 点击完成时, 触发 confirm 事件,event.detail = {value: value}
bindkeyboardheightchange eventhandle 键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration}

# keyboard-accessory

tip: 视图最大高度为 200px

示例代码

<textarea hold-keyboard="{{true}}">
  <keyboard-accessory class="container" style="height: 50px;">
    <cover-view bindtap="tap" style="flex: 1; background: green;">1</cover-view>
    <cover-view bindtap="tap" style="flex: 1; background: red;">2</cover-view>
  </keyboard-accessory>
</textarea>