数据列表页主子表配置

这篇文档适合谁

适合：

• 通过页面手工配置数据集关系的业务运营同学
• 想把“订单和订单明细”“合同和付款计划”“项目和任务”这类一对多关系配置成主子表的同学
• 需要确认主子表配置项、字段含义和验收方法的实施与交付同学

不适合：

• 想改后端事务接口或批量导入逻辑的研发同学
• 想在 React JSX 页面里自定义主子表布局的研发同学
• 想配置普通 LOOKUP 关联、枚举映射或员工选择器的同学

在数据列表页中，主子表配置用于表达“一条主记录下面有多条明细记录”的业务关系。它让平台知道哪张表是主表、哪张表是子表，以及子表通过哪个字段归属于主表，从而在列表、详情和表单中正确展示与维护明细数据。

先看问题

当业务里有“一条主记录下面有多条明细记录”时，就应该优先判断是否需要主子表。

例如：

• 一个订单下面有多条订单明细
• 一个合同下面有多条付款计划
• 一个项目下面有多条项目任务

如果没有配置主子表，常见问题是：

• 页面只能看到主表数据，看不到它下面的明细数据
• 明细表能单独维护，但不知道应该挂到哪条主表记录下面
• 数据列表页、详情页或表单需要引用明细字段时，平台无法确定正确的数据关系。
• AI 或配置同学只能凭字段名猜关系，后续页面表现不稳定

先记住这四个词：

• 主表：业务上被打开、查看和管理的主记录，例如订单、合同、项目
• 子表：依附在主记录下面的明细记录，例如订单明细、付款计划、项目任务
• 关联字段：子表里保存主表记录标识的字段，也常被叫作外键
• 一对多：一条主表记录可以对应多条子表记录

一句话结论

• 主子表本质是一种明确的一对多业务关系
• 子表必须有字段能指向主表记录
• 配置时要同时填清楚主表、子表、关联字段和业务关系类型
• 配完后一定用一条主记录和多条子记录验证关系是否正确

在数据集关系里，主子表通常对应：

• cardinality：one_to_many
• bizRelationType：main_sub

不要只因为两张表字段名相似就配置主子表。判断重点是：业务上是不是“一条主记录拥有多条明细记录”，以及子表里是否真的有字段保存主表记录标识。

接下来要配置哪两张表

以“订单 + 订单明细”为例：

• 主表：order
• 子表：order_item
• 主表主键字段：id
• 子表关联字段：order_id
• 关系类型：主子表
• 基数：一对多

你不需要先理解底层实现，只需要确认这两件事：

1. 哪张表是业务入口，也就是主表
2. 子表里哪个字段保存了主表记录的标识

如果找不到子表里的关联字段，不要先配置主子表。应先补齐数据模型，或者确认这两张表是否只是普通关联。

修改前先判断是否适用

适合配置主子表的场景：

• 订单和订单明细
• 合同和付款计划
• 报销单和费用明细
• 项目和项目任务
• 其他“一条主记录下面有多条明细记录”的业务

不适合按主子表配置的场景：

• 员工和部门这类普通归属关系
• 订单和客户这类多条订单引用同一个客户的关系
• 枚举、状态、类型字典这类固定值映射
• 只是字段名相近，但业务上没有明细归属关系的两张表

简单判断方法：

1. 如果你打开一条主记录时，天然希望看到它下面的一组明细，通常适合主子表
2. 如果只是想在列表里显示另一张表的一个名称或属性，通常不是主子表
3. 如果子表没有保存主表记录标识的字段，不能直接配置主子表

操作步骤

第 1 步：进入配置入口并定位数据集

进入数据集配置有两条路径，任选一条定位到本次要配置关系的数据集即可。

路径一：从业务页面进入

先从业务页面进入页面配置页。通常是在业务页面右上角点击编辑页面。

截图：从业务页面点击编辑页面

进入页面配置页后，切换到数据编辑。

截图：在页面配置页切换到数据编辑

在当前页面使用的数据集或 DO 模型中，找到数据集关系配置区域。

截图：打开数据集关系配置

路径二：从 RabetBase 数据集总览进入

打开 RabetBase 的数据集总览，在总览中定位到本次要配置的主表数据集。建议按数据集名称或编码确认，避免进入名称相近但不属于当前业务页面的数据集。

截图：从 RabetBase 数据集总览定位主表数据集

定位后进入该数据集的配置详情，再继续确认主表字段、子表字段和数据集关系。

第 2 步：确认主表字段

先确认当前业务页面对应的是哪张主表。

以订单页面为例，当前页面的数据集应该是订单主表。主表里至少要有一个能唯一标识记录的字段，例如：

• 字段编码：id
• 字段名称：订单 ID
• 字段含义：每一条订单记录的唯一标识

主表字段确认错了，后面关系即使保存成功，页面也很容易查不到正确明细。

第 3 步：确认子表字段

再确认子表是否有字段指向主表。

以订单明细为例，子表里通常会有：

• 字段编码：order_id
• 字段名称：订单 ID
• 字段含义：当前明细属于哪一条订单

这一步一定要确认字段含义，而不是只看字段名。比如 order_no 可能是订单编号，未必是主表主键；order_id 才更可能是和主表 id 对应的关联字段。

第 4 步：新增主子表关系

在数据集关系配置里点击新增关系，或点击界面中的新增按钮，创建一条空的关系配置。

截图：创建一条待填写的主子表关系

创建后，按实际字段填写这条关系。

推荐按下面的顺序确认：

配置项	示例值	怎么判断
主表数据集	order	当前业务入口表
主表字段	id	主表记录唯一标识
子表数据集	order_item	明细表
子表字段	order_id	子表里保存主表标识的字段
关系基数	one_to_many	一条主表记录对应多条子表记录
业务关系类型	main_sub	明确声明这是主子表

截图：选择主表、子表及关联字段

截图：设置一对多主子表关系

如果界面里字段名称不同，按页面实际文案选择即可。关键是语义要对应：主表字段和子表字段必须能真正关联到同一条主记录。

第 5 步：保存并发布

配置完成后，点击保存并发布。

截图：保存并发布主子表关系配置

如果只保存草稿或只改了本地配置，线上业务页面不会生效。发布后，再回到业务页面验证主表和子表是否能按预期关联。

第 6 步：确认子表预览、编辑和删除

保存并发布后，打开一条主表记录，先确认子表明细区能展示正确归属的明细。

如果当前页面模板提供子表操作入口，还应继续验证：

• 编辑一条子表明细后，修改结果能正确保存
• 删除一条子表明细后，该明细不再出现在当前主表记录下

子表是否支持编辑和删除，取决于当前页面模板与权限配置；主子表关系本身不自动开放这些操作。

截图：进入子表预览

截图：进入预览后的子表明细内容

截图：子表明细内容列表

截图：编辑和删除子表明细

创建主表数据时的主子表表现

主子表关系配置并发布后，如果当前主表页面已经承接主子表创建能力，创建界面通常会同时展示两部分：

• 主表表单：填写订单编号、客户等主表字段
• 子表明细区：在同一创建流程中新增一行或多行订单明细，例如商品、数量等字段

保存时，子表明细会归属到本次创建的主表记录；用户不需要把每条明细手工关联到另一条订单。

如果创建页面只显示主表字段，没有子表明细区，说明当前页面模板还没有承接主子表创建布局。主子表关系定义数据模型语义，不会自动生成子表区域。

截图：创建主表数据时的基础表单

截图：在创建流程中新增子表明细

完整配置示例

下面是一组“订单 + 订单明细”的最小示例。

主表：订单

字段编码	字段名称	说明
id	订单 ID	主表唯一标识
order_no	订单编号	业务展示编号
customer_name	客户名称	订单客户

子表：订单明细

字段编码	字段名称	说明
id	明细 ID	子表唯一标识
order_id	订单 ID	指向订单主表的 id
product_name	商品名称	明细商品
quantity	数量	明细数量

关系配置：

配置项	示例值
fromDatasetCode	order
fromField	id
toDatasetCode	order_item
toField	order_id
cardinality	one_to_many
bizRelationType	main_sub

这组配置表达的是：一条订单记录可以拥有多条订单明细，订单明细通过 order_id 归属于订单的 id。

配置项字段含义

如果页面展示的是中文表单项，按页面文案填写即可；如果看到的是 JSON 或平台字段名，可以按下面这张表核对。

字段	示例值	含义	填写要点
fromDatasetCode	order	主表数据集编码	填当前业务入口表
fromField	id	主表用于被关联的字段	通常是主表主键或稳定唯一标识
toDatasetCode	order_item	子表数据集编码	填明细表
toField	order_id	子表里保存主表标识的字段	必须能和 fromField 对上
toFieldLabel	订单 ID	子表关联字段展示名	有界面展示或自动生成需要时填写；没有该项时按平台默认值处理
cardinality	one_to_many	关系基数	主子表应是一条主记录对应多条子记录
bizRelationType	main_sub	业务关系类型	明确声明这条关系是主子表
confidence	1	关系置信度	手工确认的关系可保持平台默认高置信；不要用它替代字段核对
sourceType	manual	关系来源	手工配置、AI 识别或平台自动生成时来源可能不同，按实际来源保留

这里最容易填错的是 fromField 和 toField。主表字段是被子表引用的字段，子表字段是保存主表标识的字段，不要把两边反过来。

数据列表页里如何使用关联字段

主子表关系配置完成后，数据列表页的表格、筛选器或详情区域如果需要引用关联字段，通常使用单层点号写法：

• 列表字段：relation.field
• 筛选字段：relation.field

例如在订单页面中展示客户、明细或关联对象的字段时，页面配置可能会出现类似写法。具体字段名应以页面配置和组件语义为准。

注意：

• 只使用一层点号，不要写成多层链式关系
• 字段必须真实存在并参与当前页面的数据获取
• 主子表关系配置不等于自动生成所有页面布局，页面展示区域仍需要按实际页面能力配置

如果你要确认底层组件支持哪些字段写法，应回到 page-schema 查询字段语义：

• 数据集关系声明（主子表字段与校验规则）
• LrSmartTable 关联字段引用
• LrSmartFilter 关联字段引用
• PageSchema 点号字段限制

最终线上验收结果

发布后，建议用一条真实主记录做验收。

以订单为例：

1. 打开一条订单记录
2. 确认这条订单下面能看到对应订单明细
3. 新增或编辑一条明细后，确认它归属到当前订单
4. 换另一条订单记录，确认不会看到上一条订单的明细

验收时重点看三件事：

• 明细是否只出现在正确的主记录下面
• 新增明细时是否能带上或选择正确主表记录
• 列表、详情、筛选里引用关联字段时是否正常展示

如果配置后看不到明细，优先检查下面几项：

• 主表和子表是否选反
• 主表字段和子表字段是否能真实关联
• cardinality 是否是一对多
• bizRelationType 是否是主子表
• 是否已经执行保存并发布

常见错误

错误 1：把普通引用关系配成主子表

订单引用客户，不等于客户和订单一定要配置成主子表。订单和客户通常是普通引用关系；订单和订单明细才更像主子表。

错误 2：把主表和子表配反

如果把订单明细当主表、订单当子表，就会变成“一条明细下面有多个订单”的错误语义。判断主表时，看业务入口和页面主记录，不要只看字段位置。

错误 3：关联字段选成了展示字段

order_no 是订单编号，通常用于展示；order_id 更可能是明细表里指向主表的字段。配置关系时要选能稳定关联记录的字段，不要误选展示名称或编号。

错误 4：只改关系，没有发布

没有执行保存并发布，最终业务页面不会更新。这一点和其他页面配置教程一致。

错误 5：以为主子表关系会自动完成所有页面布局

主子表关系只是让平台知道两张表之间的业务关系。页面上是否展示明细、展示在哪里、是否允许新增和编辑，还要看当前页面模板和组件配置。

你只需要记住的判断顺序

1. 业务上是不是“一条主记录下面有多条明细记录”
2. 子表里是否有字段保存主表记录标识
3. 主表字段和子表字段是否能真实关联
4. 关系基数是否是一对多，业务关系类型是否是主子表
5. 改完后是否已经保存并发布并回到业务页面验收