安装

tnpm install --save @alipay/mas-power-form

组件介绍

强大的行业小程序信息录入及核对组件，针对支付宝行业的各个不同场景的表单验证提供支持。

参数说明

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | title | 否 | string | 标题 | 空 | 收货地址| layout | 否 | string | 表单布局方向 inline ，vertical | inline | | titleClass | 否 | string | title 的class | | | fields| 是 | array | 表单类型的每一项 | [] | | value | 否 | object | 表单各项的值(若配置了此值，此时表单为完全受控组件) | - | | defaultValue| 否 | object| 表单各项的初始值| - || onChange| 否 | function | 当表单值变化时回调函数 function(value(object): 表单各项的值)| 空函数 | | onItemChange| 否 | function | 表单某项值变化时回调函数 (key, value, allValue) => {}| 空函数 | | labelWidth | 否| string | label宽度 | 160rpx | 200rpx | validate| 否 | function | 触发表单校验 通过ref调用 返回为 Promise 实例; 实例返回值为 [errors, value] 形式 | | | validateToast| 否 | boolean | 是否开启 校验错误信息toast提示 | true | | setItemValue| 否 | function | 在非受控模式下，可通过ref调用 setItemValue(key, value)设置表单某项的值，注意需要开启componets2 | | |

defaultValue只针对第一次渲染时有效，如果在组件渲染之后defaultValue的值有变的话组件展示不会随之变化。使用value和onChange可以使组件展示实时响应value的变化。

Badges

[![install size][install-size-image]][install-size-url]

受控与非受控

受控状态(传入value属性): 表单值的变化受外部传入value决定

demo预览

页面路径: pages/controlled/index

非受控状态(不传入value属性):

demo预览

页面路径: pages/unControlled/index

rules配置

示例：

 rules:[
    { type: 'string', pattern: Schema.pattern.email, message: '请输入正确的邮箱格式' },
    { 
      validator(rule, value, callback, source, options) {
        const errors = [];
        // test if email address already exists in a database
        // and add a validation error to the errors array if it does
        return errors;
      },
    },
  ],

更详细的 rules 配置示例及解释 请参看：https://github.com/yiminghe/async-validator

属性 | 参数说明 | 属性值 | --- | :---: | :---: | type | 数据类型 | string,number,boolean,method,regexp,integer,float,array,object,enum,date,url,hex,email,any | pattern | 正则表达式 | | min | 范围最小 (对于 字符串和数组类型，将根据长度执行比较，对于数字类型，数字不能小于min也不能大于max) | number | max | 范围最大 | number | len | 指定长度（对于字符串和数组类型，其length属性需等于len；对于number类型，它只能严格等于len；如果len属性与“min”和“max”同时出现，则len优先）| number | validator | 校验函数 function(rule, value, callback) | function | asyncValidator | 异步校验函数 function(rule, value, callback) | function | message | 错误提示信息 | | enum | 枚举 { type: 'enum', enum: ['admin', 'user', 'guest'] } | [] | whitespace | 只输入空白校验 type 为 string时 生效 | true | fields | 深层校验 如对 object 类型 | { key1: { type: 'string', ... }, key2: { ... } } | defaultField | 可与数组或对象类型一起使用，以验证容器的所有值。它可以是包含验证规则的对象或数组 | | transform | function 验证前处理转换值 | () => { return newValue } |

表单校验

demo预览

页面路径: pages/validator/index

垂直排列label

demo预览

页面路径: pages/vertical/index

设置layout: vertical

fields配置

fields是数组，fields里面的每一项的格式如下:

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | mode | 是 | string | 类型： datePicker(日期选择), verifyCode(验证码), textarea（文本框）, input(输入框), optionsSelect(选项选择), multiLevelSelect(多级联选择), dynamicMultiLevelPicker(动态级联选择), switch(switch开关), phoneContact(本地通讯录), alipayContact(支付宝通讯录), scan(扫码), customClick(自定义点击项，可在点击后执行自定义的交互，最后返回需要的值)| 无 || label| 是| string | 表单项标题| 无 | 收货人 key | 是 | string | 标注表单项的key | 无 | name required | 否 | boolean | 是否为必填项（必填项红点标示，可用作表单校验条件） | 无 | disabled| 否 |boolean | 只读，不可编辑| false| | rules | 否 | array | 表单校验规则 详细请看 下方 《rules配置》 | 无 |

不同mode 特有属性

mode: datePicker

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | format | 否| string | 时间格式 (可用值：1.HH:mm 2.yyyy-MM-dd HH:mm 3.yyyy-MM 4.yyyy) | yyyy-MM-dd | | showIcon | 否| boolean | 是否展示icon | false | | currentDate | 否| string | 初始选择的日期时间 | 当前时间 | | startDate | 否| string | 最小日期时间 | | | endDate | 否| string | 最大日期时间 | | | placeholder | 否| string | 占位符 | | |

时间选择

demo预览

页面路径: pages/datePicker/index

mode: verifyCode

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | placeholder| 否 | string | 占位符| 无| | placeholderClass|否 |string | 占位符样式| 无| | maxlength| 否 |number | 最大长度| 140| | focus| 否| boolean| 获取焦点| false| | timeout| 否|number| 倒计时时间| 60| 60 onSendVeifyCode| 否 | function | 点击发送验证码时的回调函数 回传参数：(this.$page) | 空函数 | |

验证码

demo预览

页面路径: pages/verifyCode/index

mode: textarea

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | allowClear | 否 | boolean | 是否可以清空| 无 | | placeholder| 否 | string | 占位符 | 无| | placeholderClass|否 |string | 占位符样式| 无| | maxlength| 否 |number | 最大长度| 140| | focus| 否| boolean| 获取焦点| false| | autoHeight| 否 | boolean | 是否自动增高| false| | showCount| 否 | boolean | 是否渲染字数统计功能（是否删除默认计数器/是否显示字数统计）| true| | onConfirm| 否 | function| confirm触发回调函数 回传参数：({key, value}, $page) | 空函数 | | onFocus | 否 | function | focus触发回调函数 回传参数：({key, value}, $page) | 空函数 | | onBlur | 否| function | blur触发回调函数 回传参数：({key, value}, $page) | 空函数 | | canSearch| 否|boolean| 是否支持模糊搜索| false| onSearchLoadData | 否| function | 模糊搜索触发函数 会回传入参（{key, value}, $page); 请返回一个Promise实例，reslove值为 一个数组（数组元素可为 字符串或对象；当元素为对象时，对象中必须包含name属性用于显示) | 空函数 | |

demo预览

页面路径: pages/textarea/index

mode: input

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | allowClear | 否 | boolean | 是否可以清空| 无 | | placeholder| 否 | string | 占位符| 无| | placeholderClass|否 |string | 占位符样式| 无| | maxlength| 否 |number | 最大长度| 140| | focus| 否| boolean| 获取焦点| false| | type| 否 | string | input 的类型，有效值：text、 number、 idcard、 digit(可以唤起带有小数点的数字键盘)、numberpad、digitpad、 idcardpad| text| | password| 否 | boolean | 是否是密码类型| false| | confirmType| 否 | string | 设置键盘右下角按钮的文字，有效值：done（显示“完成”）、go（显示“前往”）、next（显示“下一个”）、search（显示“搜索”）、send（显示“发送”），平台不同显示的文字略有差异。注意：只有在 type=text 时有效。| done| | confirmHold| 否|boolean| 点击键盘右下角按钮时是否保持键盘不收起状态。| false| | onConfirm| 否 | function| confirm触发回调函数 回传参数：({key, value}, $page) | 空函数 | | onFocus | 否 | function | focus触发回调函数 回传参数：({key, value}, $page) | 空函数 | | onBlur | 否| function | blur触发回调函数 回传参数：({key, value}, $page) | 空函数 | | canSearch| 否|boolean| 是否支持模糊搜索| false| onSearchLoadData | 否| function | 模糊搜索触发函数 回传入参（{key, value}, $page); 请返回一个Promise实例，reslove值为 一个数组（数组元素可为 字符串或对象；当元素为对象时，对象中必须包含name属性用于显示) | 空函数 | |

模糊搜索

demo预览

页面路径: pages/inputSearch/index

mode: optionsSelect

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | title| 否 | string | 选择项名称| 无| | optionsOne| 是|array| 选择项第一项列表 (注：只传optionsOne可作为单级下拉框)| []| | optionsTwo| 否|array| 选择项第二项列表| []| | positiveString| 否|string| 确认按钮文案| 确定| negativeString| 否|string| 取消按钮文案| 取消|

普通选择

demo预览

页面路径: pages/optionsSelect/index

mode: multiLevelSelect

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | title| 否 | string | 选择项名称| 无| | multiLevelSelectItems| 是 | array | 级联数据列表| 无| |[{name: "杭州市",subList: [{name: "西湖区",subList: [{name: "古翠街道"},{name: "文新街道"}]}]}]}]

多级联选择

demo预览

页面路径: pages/multiLevelSelect/index

mode: dynamicMultiLevelPicker

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | title| 否 | string | 选择项名称| 无| | onLoadPickerData| 是 | function | 选择的值 | onLoadPickerData(key, param, $page) { return [{ name: '北京', code: '100010' }];} | |

onLoadPickerData 中的key为当前选项的key, param为选中的对象值， 需要 return [ { name: '', code: ''}]类型的数据;

动态级联选择

demo预览

页面路径: pages/dynamicMultiLevelPicker/index

mode: phoneContact

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | placeholder| 否| string| 占位符| |

mode: alipayContact

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | chooseType| 是| string| 选择类型，值为 single（单选）或者 multi（多选）| | includeMobileContactMode| 否| string| 选择手机通讯录联系人的模式。none：默认为只包含支付宝联系人，不包含手机通讯录联系人；known：仅包含双向通讯录联系人，即双方手机通讯录都存有对方号码的联系人；all：包含所有通讯录联系人| | includeMe| 否| boolean| 是否包含自己| | multiChooseMax| 否| string| 最大选择人数，仅 chooseType 为 multi 时才有效| | multiChooseMaxTips| 否| string| 多选达到上限时提示的文案，仅 chooseType 为 multi 时才有效| | placeholder| 否| string| 占位符| |

联系人

demo预览

页面路径: pages/contact/index

mode: scan

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | hideAlbum| 否|boolean| 是否隐藏相册（不允许从相册选择图片），只能从相机扫码。| false| placeholder| 否|string| 占位符| |

扫一扫

demo预览

页面路径: pages/scan/index

mode: customClick

属性 | 必填 | 参数类型 | 参数说明 | 默认值 | 示例 | --- | :---: | :---: | :---: | :---: | :---: | onClick| 是| function| 点击回调 回传参数: (key, $page) | 无| placeholder| 否| string| 占位符 | 无|

demo预览

页面路径: pages/customClick/index

如何在fields配置项的函数中获取当前page实例

业务场景中可能还会存在 在fields配置项的函数中调用当前page的setData等方法的情况； 对此，mas-power-form组件在执行每一个回调函数的时候会把 $page 放在最后一个参数位返回给函数

demo预览

页面路径: pages/getParent/index

slot

name | 说明 | --- | :---: | content-prefix | title和表单之间可以插入的内容 content-postfix| 表单后面可以插入的自定义内容 item-label-prefix-{{key}} | 特定的一行表单项 label区域 前面 可以插入的自定义内容 item-label-postfix-{{key}} | 特定的一行表单项 label区域 后面 可以插入的自定义内容 item-content-prefix-{{key}} | 特定的一行表单项 内容区域 前面 可以插入的自定义内容 item-content-postfix-{{key}} | 特定的一行表单项 内容区域 后面 可以插入的自定义内容 item-bottom-{{key}} | 特定的一行表单项内下部 可以插入的自定义内容（例如：报错信息展示；inline 模式下 默认slot的插入位置偏向content下部，可通过样式覆盖进行调整；vertical 模式下只在 content 下部） field-prefix-{{key}} | 特定的一行表单项上面可以插入的自定义内容 field-postfix-{{key}} | 特定的一行表单项下面可以插入的自定义内容

自定义插槽内容

demo预览

页面路径: pages/content/index

在小程序中使用

{
  "usingComponents": {
    "mas-power-form": "@alipay/mas-power-form/es/index"
  }
}

在 page.axml 中引用组件

<!-- 页面使用方式 -->
<mas-power-form
  title="信息核对"
  fields="{{fields}}"
  onChange="onChange"
  value="{{value}}"
>
</mas-power-form>