组件联动
在表单开发中,经常需要实现组件之间的联动行为,例如当某个输入框的值满足特定条件时,动态显示或隐藏其他组件。FormCreate 提供了强大的组件联动功能,通过 control 配置项实现组件的加载、显示、禁用和必填等状态控制。
本文将详细介绍组件联动的配置项及其用法,并通过多个示例帮助您在实际业务场景中灵活应用这些功能。
数据结构
type Control = Array<{
//通过内置条件控制,和`handle`二选一
value?: any;
//内置的条件,可以和`value`组合使用
condition?: '==' | '!=' | '<>' | '>' | '>=' | '<' | '<=' | 'in' | 'notIn' | 'on' | 'notOn' | 'between' | 'notBetween' | 'empty' | 'notEmpty' | 'pattern' | 'beforeDay' | 'afterDay' | 'beforeWeek' | 'afterWeek' | 'beforeMonth' | 'afterMonth' | 'beforeYear' | 'afterYear' | 'beforeDate' | 'afterDate' | 'period';
//自定义控制条件
handle?: (val: any, api: Api) => boolean;
//控制指定规则的显示,禁用,必填
method?: 'display' | 'disabled' | 'hidden' | 'required';
//控制的字段
rule: string[];
} | {
//通过内置条件控制,和`handle`二选一
value?: any;
//内置的条件,可以和`value`组合使用
condition?: '==' | '!=' | '<>' | '>' | '>=' | '<' | '<=' | 'in' | 'notIn' | 'on' | 'notOn' | 'between' | 'notBetween' | 'empty' | 'notEmpty' | 'pattern' | 'beforeDay' | 'afterDay' | 'beforeWeek' | 'afterWeek' | 'beforeMonth' | 'afterMonth' | 'beforeYear' | 'afterYear' | 'beforeDate' | 'afterDate' | 'period';
//自定义控制条件
handle?: (val: any, api: Api) => boolean;
//控制的规则
rule: Rule[];
//条件达成时,将`rule`添加到指定字段后面
append?: string;
//条件达成时,将`rule`添加到指定字段前面
prepend?: string;
//条件达成时,将`rule`添加到指定字段的子级, 不配置`append`和`prepend`时, 默认当前规则
child?: boolean;
}>注意
handle 优先级大于 value
推荐采用第一种组件联动形式:提前在规则中定义好所有关联组件。
method 选项
| 键名 | 配置项 | 说明 |
|---|---|---|
| if/hidden | 条件渲染 | 控制组件的显示/隐藏状态 |
| required | 必填验证 | 设置字段是否为必填项 |
| disabled/enabled | 禁用状态 | 控制组件是否可交互 |
| display | 显示状态 | 控制组件的显示状态(会渲染 DOM) |
注意
当前版本存在语义反转问题:hidden=true 时显示组件,disabled=true 时启用功能。为此新增了语义明确的 if(true显示/false隐藏)和 enabled(true启用/false禁用)参数。
condition 选项
| 键名 | 运算符 | 说明 | 值类型 | 示例 |
|---|---|---|---|---|
| == | 全等 | 组件值完全等于value | Any | value: 10 |
| != | 不全等 | 组件值不等于value | Any | value: "error" |
| <> | 不全等 | 组件值不等于value(同!=) | Any | value: false |
| > | 大于 | 组件值大于value | Number | value: 100 |
| >= | 大于等于 | 组件值大于等于value | Number | value: 18 |
| < | 小于 | 组件值小于value | Number | value: 0 |
| <= | 小于等于 | 组件值小于等于value | Number | value: 100 |
| in | 包含 | 组件值存在于value数组中 | Array | value: [1,2,3] |
| notIn | 不包含 | 组件值不存在于value数组中 | Array | value: ["a","b"] |
| on | 包含值 | value存在于组件值(数组)中 | String | Number |
| notOn | 不包含值 | value不存在于组件值(数组)中 | String | Number |
| between | 区间内 | 组件值在value[0]和value[1]之间 | Array[2] | value: [10,20] |
| notBetween | 区间外 | 组件值不在value[0]和value[1]之间 | Array[2] | value: [0,100] |
| empty | 为空 | 组件值为空时通过验证 | - | value: true |
| notEmpty | 非空 | 组件值不为空时通过验证 | - | value: true |
| pattern | 正则 | 用正则表达式验证组件值 | String | value:'^1\d{10}$' (不需要前后的"/") |
| beforeDay | 早于若干天前 | 组件时间早于当前时间减去 value 天 | Number | value: 7 |
| afterDay | 晚于若干天后 | 组件时间晚于当前时间加上 value 天 | Number | value: 7 |
| beforeWeek | 早于若干周前 | 按 7 天偏移,规则同 beforeDay | Number | value: 1 |
| afterWeek | 晚于若干周后 | 按 7 天偏移,规则同 afterDay | Number | value: 1 |
| beforeMonth | 早于若干月前 | 按月偏移,规则同 beforeDay | Number | value: 1 |
| afterMonth | 晚于若干月后 | 按月偏移,规则同 afterDay | Number | value: 1 |
| beforeYear | 早于若干年前 | 按年偏移,规则同 beforeDay | Number | value: 1 |
| afterYear | 晚于若干年后 | 按年偏移,规则同 afterDay | Number | value: 1 |
| beforeDate | 早于指定日期 | 组件时间早于 value | String | Date | Number | value: '2026-01-01' |
| afterDate | 晚于指定日期 | 组件时间晚于 value | String | Date | Number | value: '2026-01-01' |
| period | 固定区间 | 组件时间落在 value 指定的区间内,含起止 | String | value: 'thisMonth' |
日期用 dayjs 比较。组件值和 beforeDate、afterDate 的 value 可以是 Date、10 位秒时间戳、13 位毫秒时间戳、YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss。值是数组时,每一项都要满足条件。
偏移类的 value 是大于等于 0 的整数,比较的是当前时刻加减后的时间点,不包含这个时间点。beforeDay 的 value 为 0 表示早于现在,afterDay 为 0 表示晚于现在。beforeWeek、afterWeek 按 7 天计算,自然周用下面的 period。
period 的 value:
| value | 区间 |
|---|---|
| recent7Day | 含今天在内的近 7 天 |
| recent30Day | 含今天在内的近 30 天 |
| coming7Day | 含今天在内的未来 7 天 |
| coming30Day | 含今天在内的未来 30 天 |
| thisWeek | 本周,周一到周日 |
| lastWeek | 上周 |
| nextWeek | 下周 |
| thisMonth | 本月 |
| lastMonth | 上月 |
| nextMonth | 下月 |
| recentMonth | 从当前时刻往前 1 个月的当天 0 点,到今天结束 |
| comingMonth | 今天 0 点,到当前时刻往后 1 个月结束 |
| recent3Month | 从当前时刻往前 3 个月的当天 0 点,到今天结束 |
| recent6Month | 从当前时刻往前 6 个月的当天 0 点,到今天结束 |
| thisQuarter | 本季度 |
| lastQuarter | 上季度 |
| nextQuarter | 下季度 |
| thisYear | 今年 |
| lastYear | 去年 |
| nextYear | 明年 |
| recentYear | 从当前时刻往前 1 年的当天 0 点,到今天结束 |
| comingYear | 今天 0 点,到当前时刻往后 1 年结束 |
选择日期后,命中的条件会显示对应字段。示例包含 beforeDay、afterDay、beforeDate、afterDate,以及 period 的 recent7Day、thisWeek、thisMonth。
联动示例
追加新规则
通过评分组件的控制规则实现条件加载:当用户评分低于3星时,自动显示差评原因输入框,要求用户填写具体原因。
追加新规则到指定位置
通过输入框的控制规则实现动态表单:当input3有输入值时,自动在input1之后插入input4输入框,实现根据用户输入动态扩展表单字段的功能。
追加新规则到插槽中
通过输入框的控制规则实现动态插槽:当输入值为"child"时,自动在输入框的append插槽位置添加一个按钮,实现根据输入内容动态显示插槽内容的功能。
控制已有规则必填状态
通过输入框的控制规则实现动态必填验证:当input1输入值为"required"时,自动将input2字段设置为必填状态,实现根据条件动态调整表单验证规则的功能。
配置多个组件联动
一个输入框同时配置多个控制规则:当输入框有值时,既在输入框后缀插槽添加按钮,又动态插入评分组件,实现多条件同时触发的复杂表单交互效果。
控制已有规则显示状态
控制当前表单中的field/name组件显示状态
const control = {
value: 1,
rule: ['field1', 'name2']
}条件控制已有规则显示状态
通过条件 >= 1 控制当前表单中的field/name组件显示状态
const control = {
value: 1,
condition: '>=',
rule: ['field1', 'name2']
}控制已有规则禁用状态
控制当前表单中的field/name组件是否禁用
const control = {
value: 1,
method: 'disabled',
rule: ['field1', 'name2']
}通过条件加载新规则
当组件 value 不等于组件值时加载 rule 中的新规则到表单尾部
const control = {
value: 1,
condition: '!=',
rule:[{type:'input', field:'field',title:'field'}]
}修改其他组件插槽
条件成立后将新规则插入到goods_name组件的children中
const control = {
value:1,
prepend:'goods_name',
child: true,
rule:[{type:'input', field:'field',title:'field'}]
}分组表单监听最外层表单
分组表单里的 control 默认只在当前字段自己的值变化时重新计算。要跟着最外层表单的字段一起变化,给当前字段加上 link,字段名写成 $form.字段名。
最外层该字段变化后,会重新执行这条 control。条件函数里用 api.top.form 读取最外层表单的值。
下面的示例里,审批结果选「驳回」时,分组表单中的「驳回原因」显示出来。
{
type: 'input',
field: 'name',
title: '名称',
link: ['$form.status'],
control: [
{
handle(val, api) {
return api.top.form.status === 'reject'
},
method: 'if',
rule: ['reason']
}
]
}$form. 只在子表单、分组表单内部生效,指向最外层表单。同一张表单内的字段直接写字段名,例如 link: ['status']。


