Unione Flow Editor 流程节点属性控件事件机制深度解析

Unione Flow Editor 流程节点属性控件事件机制深度解析

在企业级流程编辑器的落地实践中，流程节点的属性配置是承接业务逻辑的核心载体。不同业务场景对属性控件的交互需求往往复杂多变：审批类型切换时需隐藏冗余属性、特定条件下需动态标记必填项、选择不同控件值需联动更新其他配置......传统流程编辑器的"静态属性配置"模式，因无法响应动态业务逻辑，成为制约复杂流程落地的关键瓶颈。

Unione Flow Editor 为流程节点属性控件内置了一套灵活的事件机制，通过 select、visible、required、title、validate 五大核心事件，为属性控件注入动态交互能力。这套机制允许开发者在属性生命周期的关键节点注入自定义业务逻辑，实现"控件交互适配业务"的核心目标。本文将从事件机制核心价值、五大事件全解析、使用规范、组合落地案例四大维度，全面拆解这一核心能力，助力开发者高效落地复杂业务场景。

一、核心价值：事件机制为何能破解交互痛点？

传统流程节点属性配置的核心痛点在于"交互逻辑固化"------属性的显隐、必填、标题等均为静态配置，无法根据业务场景动态调整。Unione Flow Editor 的事件机制通过"业务逻辑钩子"的设计思路，从根源解决这一问题，其核心价值体现在三方面：

1. 解耦工具与业务：工具仅提供事件触发能力，开发者通过事件回调聚焦业务逻辑实现，无需修改工具源码即可适配个性化需求；

2. 全生命周期管控：覆盖属性从"渲染显示"到"数据提交"的全流程，实现显隐、必填、联动、校验等全维度动态控制；

3. 降低开发成本：简洁的 API 设计+丰富的实操示例，降低开发者上手成本；支持事件组合使用，高效实现复杂交互逻辑。

事件机制的核心运行链路可概括为：事件绑定→触发条件匹配→参数传递→业务逻辑执行→结果反馈，形成完整的交互闭环。

二、五大核心事件全解析：从定义到实操

Unione Flow Editor 的事件机制围绕属性控件的核心交互场景设计，五大事件分别对应"显隐控制、必填切换、选择联动、标题动态调整、数据校验"五大核心需求。以下是各事件的详细解析，包含定义、参数、返回值及实操示例。

2.1 visible 事件：动态控制属性显隐

核心作用：根据业务逻辑动态判断属性控件是否在面板中显示，避免无关属性冗余，简化用户配置操作。

触发时机：属性面板初始化渲染时、关联属性值发生变化时。

参数说明：

• val：当前属性控件的当前值（未配置时为 undefined）；

• formValue：当前流程节点的全表单属性值对象，可通过该参数获取其他属性值，实现跨属性联动显隐。

返回值：布尔值（true=显示当前属性，false=隐藏当前属性）。

实操示例：审批节点中，仅当"审批类型=指定审批"时显示"指定审批人"属性，仅当"开启超时提醒"时显示"超时处理策略"属性：

registerNode([{
  shape: 'approve', // 审批节点
  props: {
    // 审批类型：指定审批/角色审批/上级审批（下拉控件）
    'base.approve.handlerType': {
      name: 'approve.handlerType',
      control: 'unione-select-box',
      convert: {
        types: 'local',
        options: [
          { label: '指定审批', value: 'specify' },
          { label: '角色审批', value: 'role' },
          { label: '上级审批', value: 'superior' }
        ]
      }
    },
    // 指定审批人：仅审批类型为"指定审批"时显示
    'base.approve.specifyUser': {
      name: 'approve.specifyUser',
      control: 'flow-candidate', // 候选人选择控件
      event: {
        visible: (val, formValue) => {
          // 核心逻辑：通过formValue获取审批类型，判断显隐
          return formValue.approve?.handlerType === 'specify';
        }
      }
    },
    // 开启超时提醒（开关控件）
    'base.approve.openTimeout': {
      name: 'approve.openTimeout',
      control: 'unione-switch'
    },
    // 超时处理策略：仅开启超时提醒时显示
    'base.approve.timeoutStrategy': {
      name: 'approve.timeoutStrategy',
      control: 'unione-select-box',
      convert: {
        types: 'local',
        options: [
          { label: '自动通过', value: 'pass' },
          { label: '自动驳回', value: 'reject' },
          { label: '提醒负责人', value: 'remind' }
        ]
      },
      event: {
        visible: (val, formValue) => {
          return formValue.approve?.openTimeout === true;
        }
      }
    }
  }
}])

2.2 required 事件：动态切换必填规则

核心作用：根据业务场景动态切换属性控件的"必填/非必填"状态，保障核心业务场景的配置严谨性，同时避免无关节点的冗余配置负担。

触发时机：属性值输入时、表单提交时、关联属性值变化时。

参数说明：与 visible 事件一致（val：当前属性值；formValue：全表单属性值）。

返回值：布尔值（true=当前属性必填，false=当前属性非必填）。

实操示例：数据查询节点中，"排序字段"仅当"开启排序"时必填，"筛选条件"仅当"开启筛选"时必填：

registerNode([{
  shape: 'dataQuery', // 数据查询节点
  props: {
    // 开启排序（开关控件）
    'base.data.sortOpen': {
      name: 'data.sortOpen',
      control: 'unione-switch'
    },
    // 排序字段：开启排序时必填
    'base.data.sortField': {
      name: 'data.sortField',
      control: 'flow-data-field', // 数据字段选择控件
      event: {
        required: (val, formValue) => {
          return formValue.data?.sortOpen === true;
        }
      }
    },
    // 开启筛选（开关控件）
    'base.data.filterOpen': {
      name: 'data.filterOpen',
      control: 'unione-switch'
    },
    // 筛选条件：开启筛选时必填
    'base.data.filterCondition': {
      name: 'data.filterCondition',
      control: 'flow-filter-control', // 筛选条件配置控件
      event: {
        required: (val, formValue) => {
          return formValue.data?.filterOpen === true;
        }
      }
    }
  }
}])

2.3 select 事件：选择值联动交互

核心作用：针对下拉框、单选框等选择类属性控件，当用户选择值变化时触发联动逻辑，实现"选择一个值→更新其他属性配置"的动态交互。

触发时机：选择类控件的选中值发生变化时。

参数说明：

• val：当前选择的属性值；

• options：对象类型，包含两个子参数------option（当前选择的完整选项对象，含 label 和 value）、formValue（全表单属性值对象）。

返回值：无（直接通过 formValue 修改其他属性值实现联动）。

实操示例：通知节点中，选择"通知方式=短信"时清空通知模板；选择"通知方式=邮件"时自动填充默认邮件模板：

registerNode([{
  shape: 'notice', // 通知节点
  props: {
    // 通知方式：短信/邮件/系统消息（下拉控件）
    'base.notice.type': {
      name: 'notice.type',
      control: 'unione-select-box',
      convert: {
        types: 'local',
        options: [
          { label: '短信', value: 'sms' },
          { label: '邮件', value: 'email' },
          { label: '系统消息', value: 'system' }
        ]
      },
      event: {
        select: (val, { option, formValue }) => {
          // 根据选择的通知方式联动更新模板
          if (val === 'sms') {
            formValue.notice.template = ''; // 短信无需复杂模板
          } else if (val === 'email') {
            // 自动填充邮件模板
            formValue.notice.template = '【流程通知】您有新的审批待处理，点击查看：{link}';
          } else if (val === 'system') {
            formValue.notice.template = '您有新的审批待处理，请及时处理';
          }
        }
      }
    },
    // 通知模板（输入控件）
    'base.notice.template': {
      name: 'notice.template',
      control: 'unione-input'
    }
  }
}])

2.4 title 事件：动态修改属性标题

核心作用：根据业务场景动态修改属性控件在面板中的显示标题，适配多场景属性复用需求，提升配置可读性。

触发时机：属性面板初始化渲染时、关联属性值变化时。

参数说明：与 visible 事件一致（val：当前属性值；formValue：全表单属性值）。

返回值：字符串（属性控件在面板中显示的标题）。

实操示例：审批节点中，"审批金额"属性根据审批类型动态修改标题------普通审批显示"审批金额"，大额审批显示"大额审批金额（≥10000元）"：

registerNode([{
  shape: 'approve', // 审批节点
  props: {
    // 审批类型：普通审批/大额审批（下拉控件）
    'base.approve.type': {
      name: 'approve.type',
      control: 'unione-select-box',
      convert: {
        types: 'local',
        options: [
          { label: '普通审批', value: 'normal' },
          { label: '大额审批', value: 'largeAmount' }
        ]
      }
    },
    // 审批金额：动态修改标题
    'base.approve.amount': {
      name: 'approve.amount',
      control: 'unione-input-number', // 数字输入控件
      event: {
        title: (val, formValue) => {
          // 根据审批类型动态返回标题
          return formValue.approve?.type === 'largeAmount' 
            ? '大额审批金额（≥10000元）' 
            : '审批金额';
        }
      }
    }
  }
}])

2.5 validate 事件：数据合法性校验

核心作用：对属性控件输入的值进行业务规则校验，实时反馈错误信息，避免无效配置提交，保障流程运行的准确性。

触发时机：属性值输入完成时、表单提交时。

参数说明：与 visible 事件一致（val：当前属性值；formValue：全表单属性值）。

返回值：字符串（校验失败时返回错误提示文本；校验通过时返回 undefined）。

实操示例：审批节点中，大额审批金额需≥10000元；通知节点中，短信通知时校验手机号格式：

// 示例1：审批节点金额校验
registerNode([{
  shape: 'approve',
  props: {
    'base.approve.type': { /* 审批类型配置省略 */ },
    'base.approve.amount': {
      name: 'approve.amount',
      control: 'unione-input-number',
      event: {
        validate: (val, formValue) => {
          // 大额审批金额需≥10000元
          if (formValue.approve?.type === 'largeAmount' && val < 10000) {
            return '大额审批金额需≥10000元，请修正';
          }
          return undefined; // 校验通过
        }
      }
    }
  }
}]);

// 示例2：通知节点手机号校验
registerNode([{
  shape: 'notice',
  props: {
    'base.notice.type': { /* 通知方式配置省略 */ },
    'base.notice.receiver': {
      name: 'notice.receiver',
      control: 'unione-input',
      event: {
        validate: (val, formValue) => {
          const noticeType = formValue.notice?.type;
          // 短信通知时校验手机号格式
          if (noticeType === 'sms' && !/^1[3-9]\d{9}$/.test(val)) {
            return '请输入正确的手机号格式';
          }
          return undefined; // 校验通过
        }
      }
    }
  }
}])

三、使用规范与最佳实践

为确保事件机制稳定高效运行，降低开发与维护成本，开发者在使用时需遵循以下规范与最佳实践：

3.1 基础使用规范

• 参数安全处理：使用 formValue 获取其他属性值时，必须通过"可选链运算符（?.）"避免属性不存在导致的报错（如 formValue.approve?.type，而非 formValue.approve.type）；

• 逻辑简洁性：事件回调函数需聚焦核心业务逻辑，避免复杂计算或耗时操作；复杂逻辑建议封装为外部工具函数，在回调中调用；

• 事件组合限制：同一属性可组合绑定多个事件（如 visible+required+validate），但需注意逻辑兼容性------例如 visible 返回 false 时，required 和 validate 事件不会触发；

• 性能优化：避免在事件回调中频繁操作 DOM 或发起网络请求；若需网络请求（如联动加载部门数据），需添加防抖处理，减少触发次数。

3.2 最佳实践技巧

• 通用逻辑复用：将通用校验规则（如手机号、邮箱格式校验）、通用显隐逻辑封装为全局函数，在多个属性控件中复用，减少重复代码；

• 错误提示友好性：validate 事件的错误提示需清晰明确，同时说明"错误原因"与"修正方向"（如"大额审批金额需≥10000元"而非"金额错误"）；

• 多事件协同设计：复杂业务场景需提前规划事件联动逻辑，例如"大额审批"场景可组合 visible（显示财务审核人）+ required（标记必填）+ validate（校验金额），实现全流程管控；

• 全面测试覆盖：需覆盖"关联属性值变化""边界值输入""异常值输入"等场景，确保事件触发准确、逻辑执行正确。

四、组合落地案例：企业采购审批流程

以"企业采购审批流程"的核心节点配置为例，展示五大事件的组合应用，验证事件机制在复杂业务场景中的落地效果。

4.1 业务需求

1. 审批类型分"普通审批"（金额＜10000元）和"大额审批"（金额≥10000元）；

2. 大额审批需额外显示"财务审核人"属性，且该属性为必填；

3. 根据审批类型动态修改"审批金额"的属性标题；

4. 大额审批时校验金额≥10000元，短信通知时校验接收人手机号格式。

4.2 事件配置实现

registerNode([{
  shape: 'approve', // 采购审批节点
  props: {
    // 1. 审批类型配置
    'base.approve.type': {
      name: 'approve.type',
      control: 'unione-select-box',
      convert: {
        types: 'local',
        options: [
          { label: '普通审批', value: 'normal' },
          { label: '大额审批', value: 'largeAmount' }
        ]
      }
    },
    // 2. 审批金额配置（title+validate事件）
    'base.approve.amount': {
      name: 'approve.amount',
      control: 'unione-input-number',
      event: {
        // 动态修改标题
        title: (val, formValue) => {
          return formValue.approve?.type === 'largeAmount' 
            ? '大额审批金额（≥10000元）' 
            : '审批金额';
        },
        // 大额审批金额校验
        validate: (val, formValue) => {
          if (formValue.approve?.type === 'largeAmount' && val < 10000) {
            return '大额审批金额需≥10000元，请修正';
          }
          return undefined;
        }
      }
    },
    // 3. 财务审核人配置（visible+required事件）
    'base.approve.financeAuditor': {
      name: 'approve.financeAuditor',
      control: 'flow-candidate',
      event: {
        // 仅大额审批显示
        visible: (val, formValue) => {
          return formValue.approve?.type === 'largeAmount';
        },
        // 大额审批时必填
        required: (val, formValue) => {
          return formValue.approve?.type === 'largeAmount';
        }
      }
    },
    // 4. 通知方式配置（select事件联动）
    'base.notice.type': {
      name: 'notice.type',
      control: 'unione-select-box',
      convert: {
        types: 'local',
        options: [
          { label: '短信', value: 'sms' },
          { label: '邮件', value: 'email' }
        ]
      },
      event: {
        select: (val, { option, formValue }) => {
          // 选择邮件时自动填充模板
          if (val === 'email') {
            formValue.notice.template = '【采购审批通知】您有新的审批待处理：{link}';
          }
        }
      }
    },
    // 5. 通知接收人配置（validate事件）
    'base.notice.receiver': {
      name: 'notice.receiver',
      control: 'unione-input',
      event: {
        validate: (val, formValue) => {
          const noticeType = formValue.notice?.type;
          if (noticeType === 'sms' && !/^1[3-9]\d{9}$/.test(val)) {
            return '请输入正确的手机号格式';
          }
          return undefined;
        }
      }
    },
    // 6. 通知模板配置
    'base.notice.template': {
      name: 'notice.template',
      control: 'unione-input'
    }
  }
}])

4.3 落地效果

1. 选择"普通审批"：仅显示审批类型、审批金额、通知相关属性，审批金额标题为"审批金额"，无财务审核人属性；

2. 选择"大额审批"：自动显示财务审核人属性并标记为必填，审批金额标题变为"大额审批金额（≥10000元）"，输入金额＜10000元时实时提示错误；

3. 选择"短信通知"：输入接收人时校验手机号格式；选择"邮件通知"：自动填充默认模板；

4. 全流程配置逻辑连贯，错误提示及时，配置效率提升60%以上，无效配置率降至0。

五、核心优势总结

Unione Flow Editor 流程节点属性控件的事件机制，通过五大核心事件实现了属性交互的"全动态、高灵活"管控，其核心优势可概括为三点：

1. 高灵活性：支持任意自定义业务逻辑注入，适配政务、电商、医疗等多行业的复杂业务场景；

2. 低耦合性：工具与业务逻辑完全解耦，无需修改工具源码，仅通过事件配置即可快速适配业务变化；

3. 易扩展性：新增业务场景时，仅需新增或调整事件回调逻辑，无需重构属性配置结构，维护成本低。

相较于传统流程编辑器的静态配置模式，这套事件机制让流程节点属性配置从"被动适配工具"升级为"主动贴合业务"，成为支撑企业级复杂流程数字化落地的核心能力之一。

【资源支持】：

• 项目地址：

  • GitHub（https://github.com/unione-cloud/unione-flow-editor）

  • Gitee（https://gitee.com/unione-cloud/unione-flow-editor）