表单及校验

1. 功能描述

创建input, select, button等类型的表单元素,同时提供表单提交、表单重置、表单赋值、获取表单数据等功能。

2. 使用方法

2.1 创建实例

首先定义form标签,并设置id。然后调用如下方法:

const form = McrbHttpClient.form(form_id)

form.render(options)

form_id为form元素的id, options为表单配置,表单配置详见表单配置

2.2 实例方法

获取某一字段的值:form.getValue(name)

获取所有表单项的值:form.allValues()

对某一字段进行赋值:form.setValue(name, value)

批量赋值:form.setValues(obj), obj = { name1: value1, name2: value2...}

3. 表单配置options

表单配置options为一个数组,数组中每个元素为一个表单元素的配置对象(option)。

option对象格式如下:

{
    type: 'input', // 表单元素类型
    label: '姓名', // 元素label
    name: 'name', // 元素的name属性
    required: true, // 是否为必填项
    placeholder: '请输入姓名', // 其placeholder属性对应值
    readOnly:false, //是否只读
    ...
}

目前支持表单元素的类型如下:

3.1.input

配置参数如下:

type(String)input
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
verify (Array[String])字符串数组,表单验证参数。目前可以取值:phone, email, url, number,double, date, identity,noChinese
placeholder (String)其placeholder属性对应值
unit (String)单位。如m,kg等
custom (String | Dom)自定义区块,添加在input后,class名称“mcb-input-custom”
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

dependOn 每个Objcet字段及代表的含义如下

field(String)依赖字段名
value (String || Array)当field 依赖字段名 选择name为11时才显示 ;如果依赖字段是radio/selectInput/checkbox 可以 value:[1,2] 当选择value为1或2时显示,

3.2.textarea

type(String)textarea
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
placeholder (String)其placeholder属性对应值
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

3.3.select(废弃)

type(String)select
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
opts (Object)例:opts: {'请选择颜色': '','红色': 1,'绿色': 2}Key为选项显示的值,value为表单提交时的值,空串代表默认项。

3.4.selectInput

type(String)selectInput
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
opts (Array[Object])例:opts: [{value: '', text: '请选择', selected: true}, {value: 1, text: '红色'}, {value: 2, text: '绿色'}, {value: 3, text: '黄色'}]
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },
apiConfig (Object)异步数据+ dependField依赖字段 ;Object内容如下表;例:apiConfig: {staticData: getRescueTeam, // 函数,返回 Promise,resolve 数据数组 valueField: 'id', // 数据中的值字段 textField: 'team_name', // 数据中的显示文本字段defaultOption: '请选择救援队', dependField: 'name', // 依赖字段名params: function( dependVal ) { // dependVal 是 name 字段的当前值} }

apiConfig每个Objcet字段及代表的含义如下

staticData (Function)函数,返回 Promise,resolve 数据数组
valueField (String)数据中的值字段-对应opts中的value
textField (String)数据中的显示文本字段-对应opts中的text
defaultOption (String)opts的默认空Option ;不填则代表没有空值
dependField (String)依赖字段名;这个是异步数据依赖其他字段的值
params callback( Function( dependVal ) )// dependVal 是 status 字段的当前值 return { status: dependVal }; return 的值作为staticData这个方法的参数

3.5.radio

type(String)radio
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
radioList(Object[])每个单元按钮选项的配置
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

raidoList中每个Objcet字段及代表的含义如下:

id(String)Radio按钮的及其label(for属性)对应的id
value(String/Number)该radio对应的值(提交表单时提交的值)
label (String)该radio对应的label,自定义。
checked(Boolean)是否被默认选中
showIcon(Boolean)是否为图标+文字形式的radio
iconPath(String)图标的路径

3.6.checkbox

type(String)checkbox
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
checkboxList Object[])每个单元按钮选项的配置
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

checkboxList中每个Objcet字段及代表的含义如下:

id(String)Checkbox按钮的及其label(for属性)对应的id
value(String/Number)该Checkbox对应的值(提交表单时提交的值)
text (String)该Checkbox对应的label,自定义。
checked(Boolean)是否被默认选中
showIcon(Boolean)是否为图标+文字形式的checkbox
iconPath(String)图标的路径

3.7.upload

type(String)upload
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
maxSize(Number)上传文件的最大大小,单位Mb
btnText(String)上传按钮显示的文字
progressBar(Boolean)是否显示上传进度条
isImg(Boolean)是否只上传图片,且有缩略图
isMulti(Boolean)是否支持多文件/图片上传
fileType(String或Array[String])isImg为真时无效。input的accept属性值。例:image/*, audio/*, video/*, .pdf, .doc, .xls, .mp4, .png等。默认值:所有类型文件。
callback上传之后的回调函数
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

3.8.button

type(String)button
name (Array[String])按钮组显示的名字。
event (Array[String])字符串数组,可取值:submit, reset, cancel。表示按钮对应的事件
callback (Array[Function])函数数组,表示按钮事件对应的回调函数。
beforeSumbit (Function)表单提交前的回调函数,用于处理特殊校验等。返回一个布尔类型的值,返回true时,表单正常进入提交流程,返回false时,提交终止。

3.9.edittext

type(String)edittext
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
setdata(Object)编辑器参数项设置:
Id编辑器绑定元素的id;
width编辑器宽;
height编辑器高;
filePostName上传图片接口中file参数名;
uploadJson上传图片接口地址;

3.10.video

type(String)video
label (String)元素label,自定义。
name (String)元素的name属性。
maxSize (Number)视频文件最大多少MB
required (Boolean)是否为必填项
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

3.11.switch (开关)

type (String)switch
label (String)元素label,自定义。
name (String)元素的name属性。
active (Boolean)开关是否打开
required (Boolean)是否为必填项
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

3.12.map(拾点器)

注意事项:使用map组件时,需要设置高德地图的key、securityJsCode及version(默认值为1.4.15, 可选2.0)

type (String)map
label (String)元素label,自定义。
name (String)元素的name属性。
width(String)地图宽度(可选,默认值为100%)
height(String)地图高度(可选,默认值为400px)
layers(Array)地图图层(非必填),satellite卫星图,roadNet路网图
required (Boolean)是否为必填项
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

3.13.multiple(下拉多选)

type(String)multiple
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
readOnly (Boolean)是否为只读
opts (opt[])下拉多选选项列表
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

opts中每个opt字段及代表的含义如下:

text(String)选项显示的文字
value选项对应的值

3.14.datePicker(日期时间选择器)

type(String)datePicker
label (String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
readOnly (Boolean)是否为只读
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

3.14-1 datePickerPro(日期时间选择器增强版)

type (String)固定值:datePickerPro
label (String)元素label,自定义。
name (String)元素的name属性,用于表单取值(allValues)与赋值(setValues)。
required (Boolean)是否为必填项。为 true 时提交表单会自动校验不能为空。
readOnly (Boolean)是否为只读。只读时输入框置灰,且无法点击弹出面板。
help (String | Dom)辅助文字,添加在input后,class名称"mcb-form-help"
dependOn (Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },
mode (String)模式选择,默认 'single'。可选:single(单日) / time(仅时间) / range(日期范围) / week(周) / month(月) / year(年) / quarter(季度)
time (Boolean)在 single(单日) 或 range(范围) 模式下,是否开启时分秒的选择。
placeholder (String)输入框的提示文字,默认 '请选择'。
minDate (String | Date)最小可选日期,早于该日期的不可选。例如 'today' 或 '2026-01-01'。
maxDate (String | Date)最大可选日期,晚于该日期的不可选。
disableDates (Array | Function)禁用特定日期。传数组如 ['2026-10-01'];传函数如 function(date) { return date.getDay() === 0 }(禁用周日)。
disableTimeRanges (Array)禁用特定时间段(开启 time 时生效),如 [['00:00', '08:00'], ['22:00', '23:59']]。
dynamicDisable (Function)动态禁用。每次打开面板时执行。返回 { minDate, maxDate, disableDates, disableTimeRanges }。
separator (String)range 范围模式下的连接符,默认 ' ~ '。
onChange (Function)值变化时的回调函数,格式:function(value, state) {}

3.15.dragUpload(拖拽上传)

type(String)dragUpload
label(String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
multiple (Boolean)是否可以上传多个文件
maxSize (Number)上传文件最多大小,单位kb
text (String)拖拽上传框内的自定义文字
tips (String)拖拽上传框底部的提示语
icon (String)拖拽上传框内上传图标
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

3.16. inputNumber(数字输入框)

type(String)inputNumber
label(String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
min (Number)数字输入框最小值
max (Number)数字输入框最小值
tips (String)悬停在数字输入框上时的提示语
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

3.17. bigupload(大文件上传)

type(String)bigupload
label(String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
readOnly(Boolean)是否为只读
fileType(String或Array[String])input的accept属性值。例:image/*, audio/*, video/*, .pdf, .doc, .xls, .mp4, .png等。默认值:所有类型文件。
url(String)上传api的url
success(Function)上传成功后的回调,参数upload_plugin(Object),包含属性data: 文件地址,formitem为该表单项对应的dom元素
error(Function)上传失败后的回调,参数为错误信息
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

3.18. multiSelect(多级选择器)

type(String)multiSelect
label(String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
lastVal (Boolean)是否用所选择的最低级选择器的值最为最终的整体值,默认值为false。当三级选择器的值分别为1,2,3,lastVal值为true时,最终的值为3;当lastVal值为false时,最终的值为1,2,3。
group[Array])多级选择器的配置项(item)组合。
help(String | Dom)辅助文字,添加在input后,class名称“mcb-form-help”
dependOn(Object)联动显隐/必填 例:dependOn: {field: "name", value: '11' },

配置项item中包含属性如下

level (Number)选择器的等级
opts (Array)选项数组,每个选项包含text(选项显示的文字,String类型),value(选项的值,String类型)。
onChange (Function)当前等级选择器值发生改变时(点击选项dom触发),触发的回调。参数为选择器选择选项的值,返回值为下一个等级的选项数组opts

3.19. sms (手机验证码)

type(String)sms
label(String)元素label,自定义。
name (String)元素的name属性。
required (Boolean)是否为必填项
verify (Array[String])字符串数组,表单验证参数。目前可以取值:phone, email, url, number,double, date, identity,noChinese
btnText (String)按钮文字 // 默认'获取验证码'
sendSmsCallback callback(Function(phone, btnElement))参数phone 是输入框的phone值, btnElement 获取验证码这个按钮

4. 分组表单

type(String)group
label(String)分组表单标题
children (Array[String])表单配置options

应用实例:

<form id="testffff"></form>
<script type="text/javascript">

if(document.getElementById("testffff")){

    let testForm = McrbHttpClient.form('testffff');

    let options1 = [

        { type: "selectInput",

            name: "color",

            required: true,

            label: "所属职业",

            opts: [

                {value: '', text: '请选择职业',selected: true},

                {value: 1, text: '工程师'},

                {value: 2, text: '教师'},

                {value: 3, text: '厨师'}

            ],

            help: '必须填写',

        },

        {

            type: "selectInput",

            name: "asyncSelect",

            required: false,

            label: "职业变化select值变",

            apiConfig: {

                staticData: getTeam,   // 函数,返回 Promise,resolve 数据数组

                valueField: 'id',          // 数据中的值字段

                textField: 'team_name',         // 数据中的显示文本字段

                defaultOption: '请选择公司',

                dependField: 'color',   // 依赖字段名

                params: function( dependVal ) {

                    // dependVal 是 status 字段的当前值

                    return { status: dependVal };

                }

            },

            help: '<span style="color:red">依赖所属职业</span>',

        },

        { label: "multiselect",

            type: "multiSelect",

            name: "address",

            required: true,

            lastVal: true,

            group: [

                {level: 1, opts: [{text: '请选择', value: ''},{text: "辽宁省", value: "1"}, {text: "广东省", value: "2"}], onChange: getCity},

                {level: 2, opts: []}

            ]

        },{ type: 'datePicker',

            label: '出生时间',

            name: 'ctime',

            required: false,

            // readOnly: true

        },{ type: 'multiple',

            name: 'fruit',

            label: '水果',

            opts: [

                {text: '苹果', value: 1},

                {text: '桃子', value: 2},

                {text: '梨', value: 3},

            ]

        },{ type: "radio",

            label: "性别",

            name: "sex",

            required: true,

            radioList: [

                { id: "nan", value: 1, label: "男", checked: true },{ id: "nv", value: 2, label: "女" },

            ],

        },{ type: "upload",

            label: "图片上传(依赖性别值为'男'为时显示,'女'为不显示)",

            name: "img",

            required: true,

            maxSize: 5,

            btnText: "上传",

            isImg: true,

            callback: function(data){

                console.log(data);

            },

            dependOn: {

                field: "sex",

                value: [1]  // 只有选择sex为1时才显示

            },

        },

        { type: "bigupload",

            label: "大文件上传",

            name: "bigfile",

            required: true,

            url: "http://yourdomin/api/upload", // 使用时填写您的真实上传api的url

        },

        { type: 'switch',

            name: 'testswitch',

            label: '是否有效',

            active: true

        },{ type: "checkbox",

            label: "技能",

            name: "skill",

            checkboxList: [

                {id: "1", value: 1, text: "射击", checked: true},

                {id: "2", value: 2, text: "游泳"},

                {id: "3", value: 3, text: "骑马"},

            ]

        },{ type: "radio",

            label: "标注",

            name: "biaozhu",

            radioList: [

                { id: "biaozhu1", value: 1, label: "标注1", checked: true, showIcon:true, iconPath:'https://mhc.ixiera.com/img/bz.png' },{ id: "biaozhu2", value: 2, label: "标注2", showIcon:true, iconPath:'https://mhc.ixiera.com/img/bz.png' },

            ],

        },{ type: "checkbox",

            label: "课程",

            name: "mendian",

            checkboxList: [

                {id: "1", value: 1, text: "课程1", checked: true, showIcon:true, iconPath:'https://mhc.ixiera.com/img/bz.png'},

                {id: "2", value: 2, text: "课程2", showIcon:true, iconPath:'https://mhc.ixiera.com/img/bz.png'},

                {id: "3", value: 3, text: "课程3", showIcon:true, iconPath:'https://mhc.ixiera.com/img/bz.png'},

            ]

        },

        { type: 'dragUpload',

            name: 'dragupload',

            label: '拖拽上传' },

        { type: 'inputNumber',

            name: 'inputNumber',

            label: '人数',

            min: 0 },

        { type: "textarea",

            label: "描述",

            name: "description",

            required: false,

            placeholder: "请简要描述…",

        },{ type: "video",

            name: "svideo",

            label: '小视频' },{ type: 'map',

            label: 'map测试',

            name: 'maptest',

            width: '100%',

            height: '500px',

            layers: ['satellite'] },{ type: "edittext",

            // label: "编辑器",

            name: "content_body",

            required: false,

            setdata:{

                id:'column_content',

                width:'700px',

                height:'440px',

                filePostName:'ggggggg',

                uploadJson:'XXXXX/XXXXX/upload?actype=10',

            }

        },{ type: "button",

            event: ["submit"],

            callback: [onSubmit],

            name: ["确定"],

        },

    ];

    let options = [

        {

            type: 'group',

            label: '注册信息',

            children:[

                {

                    type: 'sms',

                    name: 'phone1',

                    required: false,

                    verify: 'phone',          // 自带手机号校验

                    label: '手机号',

                    placeholder: '请输入手机号',

                    // btnText: '获取验证码',

                    // 自定义发送短信函数(也可直接使用全局 sendSMS)

                    sendSmsCallback: function(phone, btnElement) {

                        // 调用发送短信接口

                        var set = { phone: phone };

                        McrbHttpClient.ho(function(e) {

                            var res = JSON.parse(e);

                            if (res.code == 200) {

                                McrbHttpClient.popup.msg(res.msg, { icon: 1 });

                                // 开始倒计时(可将倒计时逻辑放在此处或独立函数)

                                startCountdown(btnElement, 60);

                            } else {

                                McrbHttpClient.popup.msg(res.msg, { icon: 2 });

                            }

                        }, "SlideCircusController/sendPhone", set);

                    },

                   

                },

                {

                    type: "input",

                    name: "code",

                    required: false,

                    label: "输入验证码",

                    placeholder: "请输入验证码",

                }

            ]

        },

        {

            type: 'group',

            label: '基本信息',

            children: options1}

    ]

 

    function getTeam(params){

        console.log(params)

            return new Promise((resolve, reject) => {

                let list = [

                    {

                        leader: "张三",

                        team_name: "IT公司",

                        team_status: "1",

                        password: "111111",

                        team_num: "20",

                        team_type: "1",

                        id: "RT-1701327466709",

                    },

                    {

                        leader: "张三",

                        team_name: "一中",

                        team_status: "2",

                        password: "123",

                        team_num: "10",

                        team_type: "1",

                        id: "RT-1701829297303",

                    },

                    {

                        leader: "张三",

                        team_name: "二中",

                        team_status: "2",

                        team_num: "9",

                        team_type: "1",

                        id: "RT-1701829311827",

                    },

                    {

                        leader: "张三",

                        team_name: "饭店",

                        team_status: "3",

                        team_num: "9",

                        team_type: "1",

                        id: "RT-1701829311828",

                    },

                ];

                if(params.status == '1'){

                    list = list.filter(item => item.team_status == '1');

                    console.log(list);

                }else if(params.status == '2'){

                    list = list.filter(item => item.team_status == '2');

                }else if(params.status == '3'){

                    list = list.filter(item => item.team_status == '3');

                }

                resolve(list);

            });

        }

           

    function onSubmit(){

        let data = testForm.allValues();

        let color = testForm.getValue('color');

        console.log(data);

        console.log(color);

    }

    function getCity(value) {

        let opts

        if (value == 1) {

            opts = [

                {text: '请选择', value: ''},

                {text: "沈阳市", value: "1"},

                {text: "大连市", value: "2"},

                {text: "鞍山市", value: "3"},

                {text: "抚顺市", value: "4"},

                {text: "本溪市", value: "5"},

                {text: "丹东市", value: "6"},

            ]

        } else if (value == 2) {

            opts = [

                {text: '请选择', value: ''},

                {text: "深圳市", value: "1"},

                {text: "广州市", value: "2"},

                {text: "珠海市", value: "3"},

                {text: "汕头市", value: "4"},

                {text: "韶关市", value: "5"},

                {text: "佛山市", value: "6"},

            ]

        }

        return new Promise((resolve, reject) => {

            setTimeout(() => {

                resolve(opts)

            }, 1000)

        })

    }

    testForm.render(options);

}

</script>

 

 

 

效果展示:

线上demo地址:

https://mhc.ixiera.com/html/componentDemo/mic-form.html

 
本文档来自—microbee-http 丨 软件开发框架平台