表单客制化（Form Hook）

系统通过 Form Hook（表单级 Hook） 与 Data Hook（数据级 Hook） 提供表单层 面的客制化能力，用于实现字段默认值、联动、显隐、只读、必填、备选项、数据变换等 行为。该能力取代了早期版本中的字段级客制化（Field Hook / Dynamic Field Hook）， 后者已从平台中移除。

目标读者

本文档的目标读者为：本系统的开发和实施人员

概述

Form Hook 与 Data Hook 均关联一个 Dynamic Logic 对象，通过 DynamicForm 上的三个字段进行配置：

字段	类型	说明
formHook.name	DynamicLogic	表单级 Hook：字段默认值、联动、显隐、只读、必填、备选项等
formHookTriggerFields	String	逗号分隔的字段名列表；这些字段在界面上发生变更时，会触发 Form Hook 重新执行
dataHook.name	DynamicLogic	数据级 Hook：对列表/详情返回数据做变换

提示

旧版文档中的「字段客制化」（Dynamic Field Hook、Field dependencies hook、字段快捷 搜索逻辑等）已随平台演进移除，相关能力统一由 Form Hook 提供，请勿再按旧方式配置。

Form Hook（表单级 Hook）

触发时机

Form Hook 在以下时机执行：

1. 表单初始化：创建/编辑表单加载时执行，用于设置字段默认值与字段属性。
2. 字段变更触发：formHookTriggerFields 中任一字段的值在界面上发生变化时 执行（initiated = true），用于字段联动。
3. 详情/列表数据展示：打开记录详情或加载列表数据时执行，用于按记录内容动态 调整字段属性。

注入变量

Form Hook 执行时，系统注入如下变量：

变量名称	变量类型	描述
form	tech.muyan.dynamic.form.DynamicForm	当前表单对象
changedFields	java.util.List<String>	触发本次执行的字段名列表；表单初始化时为空列表
initiated	boolean	是否为字段变更触发（true）；表单初始化时为 false
object	org.grails.web.json.JSONObject	当前操作的记录数据（创建时为空 Map，更新时为数据库中的记录）
owner	tech.muyan.dynamic.form.DynamicForm	当前表单所属组织（数据权限相关）
userContext	tech.muyan.security.MuyanAuthentication	当前操作用户信息

返回结果

Form Hook 返回一个以字段 key 为键的 Map，每个字段项可包含：

键	类型	说明
value	任意	字段的默认值 / 新值
display	String	hide 隐藏字段；show 显示字段；readonly 只读显示
required	boolean	是否必填（false 时字段自动转为可空）
options / enumOptions	数组	选择类字段的备选项
min / max	数值	数值字段的校验范围
editable	boolean	是否可编辑
helpText	String	字段帮助信息
其他 FieldProps	任意	平台支持的任何字段属性（含字段组 extInfo 等）

示例：

// 根据「订单类型」字段的变更，联动「交货日期」字段
if (changedFields.contains('orderType')) {
  def type = object?.orderType
  return [
    deliveryDate: [
      value    : type == 'URGENT' ? new Date() : null,
      display  : type == 'URGENT' ? 'show' : 'hide',
      required : type == 'URGENT' ? true : false
    ]
  ]
}
// 表单初始化：为「状态」字段设置默认备选项
return [
  status: [
    value  : 'DRAFT',
    options: ['DRAFT', 'SUBMITTED', 'APPROVED']
  ]
]

配置方式

通过 CSV 种子数据在 DynamicForm.csv 中配置：

name(*),label,description,objectType.shortName(*),type.name(*),formHook.name,formHookTriggerFields,dataHook.name,extInfo,accessRequirement.name

Create order,,,Order,CREATE,order_form_hook,orderType,customer,,
List order,,,Order,LIST,,,order_list_data_hook,,

• formHook.name：关联的 Form Hook 动态逻辑名称
• formHookTriggerFields：逗号分隔的触发字段名列表
• dataHook.name：关联的 Data Hook 动态逻辑名称

真实示例

系统内置的 DynamicFormField FormHook（代码 data/groovy/formHook/dynamicFormFieldFormHook.groovy）演示了完整用法：

• initiated == false 分支：表单初始化时为「字段类型」设置默认备选项，并按字段 类型设置字段组 extInfo
• initiated == true 分支：遍历 changedFields，根据变更的字段名回填对应字段的 Label

Data Hook（数据级 Hook）

Data Hook 用于对列表与详情接口返回的数据进行变换，注入变量：

变量名称	变量类型	描述
ids	数组	列表查询的记录 id 集合
offset / cursor	数值/String	分页信息
max	数值	每页条数
owner	对象	所属组织（数据权限相关）
conditions / parsedConditions	对象	查询条件
userContext	tech.muyan.security.MuyanAuthentication	当前操作用户信息

返回值为以记录 id 为键的 Map，每项为该记录需要覆盖/补充的字段值。

提示

Data Hook 的结果同时服务于 AMIS 表单：AMIS 表单的数据通过 GET /form/data/$formId 获取，该接口会执行 Data Hook 做数据变换。

相关接口

接口	说明
POST /form/formHook/$formId	表单初始化时获取 Form Hook 数据
POST /form/$formId/refresh	字段变更后批量刷新表单字段属性
GET /data/$domainName/$id/withFormHook?formId=	详情数据 + Form Hook 结果
GET /form/data/$formId	AMIS 表单数据（含 Data Hook 变换）