表单及校验
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
扫一扫