@mas.io/mas-power-form NPM

安装

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

受控与非受控

受控状态(传入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>

async-validator mini-ali-ui @mas.io/any-style @mas.io/falcon-core @mas.io/manipulate @mas.io/mas-countdown @mas.io/mas-dynamic-multilevel-select

@infinitebrahmanuniverse/nolb-_mas @everything-registry/sub-chunk-583 @mas.io/ab-activity-signup

2 years ago

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago