# 高级字段控件

# 目标读者

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

# 概述

本文档描述了本系统中的部分高级字段控件，如子表控件的使用方法。

# 子表控件

子表控件用于在一个字段中显示和编辑一组关联对象（一对多或多对多），每行是一个关联对象。下图是 业务配置 > 用户 中查看用户详情时，「User Groups」子表（该字段标签在当前版本中未翻译）列出该用户所属的用户组（图中只截取了详情弹窗的下半部分）：

用户详情中的子表控件

# 定义

创建表单字段时，把字段显示类型（displayType）设为以下两种之一：

displayType	说明
`subTable`	显示当前对象某个一对多、多对多字段的关联对象。旧版本写法 `Sub table` 会被自动转换为 `subTable`
`relativeSubTable`	显示从当前对象出发、沿关联路径找到的另一个对象的一对多字段，路径写在字段 extInfo 的 `subTable.relativeNamePath` 中，例如订单上的 `customer.contacts` 显示订单客户的联系人。只能在已保存的对象上显示，创建表单中会一直显示加载状态

array 显示类型使用与子表相同的列表控件，一般用于列表页面中的一对多字段。

提示

1.0 起已移除「显示控件配置（DomainColumnClientSideTypeConfig）」菜单（请直接在表单字段上设置 displayType）。

# 显示属性

子表的配置分在两个地方：

子表字段自身的 extInfo：用 displayForm 指定子表使用哪个表单来决定显示哪些列，值为表单名称。按名称查找，与该表单的类型无关，一律按列表方式渲染；例如用户表单中的 User Groups 子表引用的是 SUB_TABLE 类型的 UserGroup Sub Table Form For User。不设置时使用子对象的 LIST 表单。relativeSubTable 的 relativeNamePath 也写在这里。
displayForm 指向的那个表单的 extInfo：行操作相关的配置写在它的 subTable 中，包括是否可修改、新增、删除行（updatable、creatable、deletable），是否可拖拽排序（dragSort），「创建」按钮的位置（asc），是否提供行级对象动作（enableActions）。

子表中的数据一般按 id 倒序显示；displayForm 配置了 Data Hook 时，数据和顺序由 Data Hook 决定。

示例如下：

// 1. 子表字段（表单字段）的 extInfo
// 1. extInfo of the sub-table form field
{
  /** 子表使用的表单名称（决定子表显示哪些列），不设置时使用子对象的 LIST 表单 */
  /** Name of the form rendering the sub-table (decides the columns); defaults to the LIST form of the child domain */
  "displayForm"?: "UserGroup Sub Table Form For User",
  /** 仅 relativeSubTable 使用：从当前对象出发的一对多字段路径，用点号分隔 */
  /** Only for relativeSubTable: path of a one-to-many field starting from the current object, separated by dots */
  "subTable"?: {
    "relativeNamePath"?: "customer.contacts"
  }
}

// 2. displayForm 指向的那个表单的 extInfo（行操作权限等写在这里，不是写在字段上）
// 2. extInfo of the form referenced by displayForm (row permissions etc. go here, not on the field)
{
  "subTable"?: {
    /** 是否可修改、新增、删除行；设置后覆盖默认值（默认可修改；带 mappedBy 的一对多子表要求主对象已保存才可删除，且当前不显示「创建」按钮） */
    /** Whether rows can be updated, created, deleted; overrides the defaults (updatable by default; for one-to-many with mappedBy, delete requires the owner to be saved and the "Create" button is currently not shown) */
    "updatable"?: true | false,
    "creatable"?: true | false,
    "deletable"?: true | false,
    /** 是否可拖拽排序 */
    /** Whether rows can be reordered by drag and drop */
    "dragSort"?: true | false,
    /** 为 true 时「创建」按钮放在表格底部（默认在顶部）；可拖拽排序的子表中新增行也追加到末尾 */
    /** When true the "Create" button is placed at the bottom (top by default); in drag-sortable sub-tables new rows are appended */
    "asc"?: true | false,
    /** 在操作列中提供行级对象动作，只读状态下也显示操作列 */
    /** Offers row-level object actions in the operations column, which is shown even when read-only */
    "enableActions"?: true | false
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

注意

updatable、creatable、deletable 等写在子表字段自身的 extInfo 中不会生效，必须写在 displayForm 指向的表单上。系统预置的部分种子数据（如用户、领域模型表单）仍写在字段上。
旧版本的 sortBy、keepOrder、searchModal 1.0 起已不再生效。
当前版本中，带 mappedBy 的一对多子表（例如用户的 User Groups）不显示「创建」按钮，无法在子表中新增行。

提示

子表的保存时机：

在子表某一行上点击「保存」时，该行立即创建或更新到数据库
带 mappedBy 的一对多子表，删除行立即生效；其他子表的删除在主对象保存时一起提交

对于动作参数表单，前端会将子表数据作为表单的一个属性进行提交。后端如何处理取决于动作的客制化 Core Logic 实现。

← 📊 仪表盘设计 📥 数据导入 →