引导指南(向导)

向导表单是一种多步骤的数据收集表单，它允许用户逐步填写信息。每个步骤都可以定义自 己的字段，即需要用户填写的数据项。此外，每个步骤的处理逻辑可以决定下一个步骤是什 么。

通过向导表单，用户可以按照预定的步骤逐步填写数据，每一步都集中于特定的信息要求。 用户完成当前步骤的数据输入后，根据当前步骤的处理逻辑，系统会确定下一个要显示的步 骤是什么。这种逐步引导的方式有助于用户更轻松地完成复杂或冗长的数据收集任务，并提 供了更好的用户体验。

其显示效果如下图

向导表单定义

向导技术上是一种类型为 type 为 WIZARD 的表单

指定表单样式

可以在表单的 extInfo 字段中声明垂直布局或者是水平布局。默认为水平布局。

{
  "direction"?: "vertical" | "horizontal",
}

注意

如果表单字段存在 detailPanel，则必须要用垂直布局才可以正常显示。

向导步骤定义

向导步骤通过 DynamicFormWizardStep 进行定义

向导步骤字段定义

向导步骤中显示的字段通过 DynamicFieldInstance 定义

步骤处理逻辑定义

通过类型为 Wizard core logic 类型的 DynamicLogic 进行定义

注入参数

变量名称	变量类型	描述
application	grails.core.GrailsApplication	grails 应用上下文
userContext	grails.plugin.springsecurity.userdetails.GrailsUser	当前操作的用户信息
wizard	tech.muyan.dynamic.form.DynamicForm	Wizard 对象
step	tech.muyan.dynamic.form.DynamicFormWizardStep	当前处理的 step 对象
formValues	org.grails.web.json.JSONObject	表单中传递到后台的所有字段的原始值
convertedValues	Map<String, Object>	表单中所有字段的对象值
log	Closure<?>	用于打印执行日志的 log 闭包

说明

formValues 是从页面传递过来的各参数字段的原始值，

• formValues 的 key 为 df_<fullDomainName>_<dynamicFieldDefinitionName> 的形式，示例如下

{
  "df_tech.muyan.contract.SampleContract_riskLevel":"低风险",
  "df_tech.muyan.contract.SampleContract_stampType":["合同章"],
  "df_tech.muyan.contract.SampleContract_leadDays":120,
  "df_tech.muyan.contract.SampleContract_expiryDate":"2022-08-01T23:29:00.614Z"
}

其中， df_tech.muyan.contract.SampleContract_riskLevel 中

• df_ 部分是表示该字段为 dynamic field

• tech.muyan.contract.SampleContract 部分是 dynamic field 所属的 domain

• riskLevel 部分是 dynamic field definition 的名称

• 对于包括附件在内的对象字段，如果该字段在界面上为单选，则传递的值为 java.lang.Integer 类型，如果该字段在界面上为多选，则传递的值为 List<java.lang.Integer> 。

• 对于 boolean 类型字段，其传递的为 boolean 值 true/false

• 对于日期及日期时间字段，其值为日期字符串，格式为 yyyy-MM-dd'T'HH:mm:ss.SSS'Z'(2021-10-05T23:03:51.119Z)

• 对于包括 Integer 和 Float 的数字类型字段，传递的值为 java.lang.Double 类型

formValues 处理逻辑可以对 formValues 参数直接进行修改，然后返回，前台会根据该返回值，设置向导中各字段的值

convertedValues 是根据字段的类型信息，转换为对应的对象类型的字段值。

• convertedValues 的 key 为向导中定义的动态字段的 name 字段，示例如

{
  Tags=低风险, 
  Seal Type=["合同章"], 
  Single attachment=tech.muyan.storage.StorageFieldValue : 120, 
  Multiple files=[tech.muyan.storage.StorageFieldValue : 121], 
  Expiry Date=2022-08-02T07:29:00.614, 
  企业资质=tech.muyan.storage.StorageFieldValue : 122
}

• 对于包括附件在内的对象字段，如果该字段在界面上为单选，则传递的值为对象，如果该 字段在界面上为多选，则传递的值为 List<对象>
• 附件字段对应的对象类型为 tech.muyan.storage.StorageFieldValue
• 对于 boolean 类型字段，其值为 boolean 值 true/false
• 对于日期字段，其值为 java.util.Date 类型对象
• 对于包括 Integer 和 Float 的数字类型字段，传递的值为 java.math.BigDecimal 类型

返回结果

return [
  message: "string", // 状态为 warning 或者 error 时，前台显示的警告或者错误信息
  formValues: [ //经过逻辑处理之后的表单数据，可以修改之前所有步骤收集的字段值
    //如果设置了某个在下一步骤会显示的字段的值，则该值会作为下一步骤表单显示的默认值
    df_<dynamicFieldDefinition1Name>: "xx",
    df_<dynamicFieldDefinition2Name>: 123
  ],
  // 如果需要在下一步骤显示某个字段的下拉选项，可以在此返回，格式如下
  options: [
    {
      fieldName: "xxx",
      options: [
        {
          label: "xxx1",
          value: "xxx1"
        },
        {
          label: "xxx2",
          value: "xxx2"
        },
      ]
    }
  ],
  // 如果需要在下一步骤中渲染某个瞬态字段，可以在此返回，格式如下
  // 生成 meta 可以调用 DomainMetaService.buildFieldMeta 方法
  metas: [
    {
      title: "yyy",
      dataIndex: "yyy",
      key: "yyy",
      editable: true,
      display: true,
      updatable: true,
    }
  ]
  nextStepName: 'Step 2' //下一步骤的 step 名称,
  //前台会根据此返回值，调整步骤之间的跳转逻辑，可返回此参数用来实现决策树
]

设置首个步骤字段默认值

当前 Wizard 不支持使用前置逻辑设置第一个步骤的值，如果需要设置第一个步骤的值，可 以通过跳转到 Wizard 的地址时，将参数通过 URL 参数的形式进行传递。

比如，如果需要设置第一个步骤的 name 字段的值为 test，value 字段设置为 10, 则可以通过如下地址进行跳转 /wizard/484?name=test&value=10, 可以通过 Action 生 成该 URL 并在 action 中作为 redirect 结果返回。举例如下:

1. 创建一个 confirmType 为 NO_POPUP_NO_CONFIRM, mode 为 CLASS_LEVEL 的 action, 在 action 的 coreLogic 中，返回如下的结果

return [
  redirect: "/wizard/484?name=test&value=10"
]

2. 将该 Action 与某个 DomainClass 进行绑定，即可在该 DomainClass 的列表页面中点 击该 Action 的执行按钮，跳转到 Wizard 的第一个步骤，并设置第一个步骤的值为 test和 10。