Files
aibridge/docs/control/07-table-controls.md
2026-05-18 09:28:15 +08:00

6.9 KiB
Raw Permalink Blame History

子表格控件

基本信息

属性 值
jnpfKey table
AIBridge builder build_table_field_model()
源码示例 extend/tableDemo/ 多种模式
workSystem 示例 水电费用、报价信息、个人信息、采购合同 等

基本规则

核心概念

子表格是一种嵌套表格,用于在主表单中管理多条明细数据。

关键配置

配置 说明 必填
child_table_name 子表物理表名 是
children 子表字段列表 是
show_summary 是否显示汇总 否
summary_field 汇总字段 否
addTableConf 新增弹窗配置 否
footerBtnsList 底部按钮 否
columnBtnsList 列按钮 否

AIBridge 使用

from aibridge.builders.field_model import build_table_field_model, build_field_model

# 创建子表格
table = build_table_field_model(
    label="订单明细",
    vmodel="f_order_detail_list",
    child_table_name="ord_order_detail",
    children=[
        build_field_model("商品名称", "f_product_name", "input"),
        build_field_model("规格型号", "f_spec", "input"),
        build_field_model("单位", "f_unit", "select", options=[
            {"fullName": "个", "id": "个"},
            {"fullName": "件", "id": "件"},
            {"fullName": "台", "id": "台"},
        ]),
        build_field_model("数量", "f_quantity", "inputNumber"),
        build_field_model("单价", "f_unit_price", "inputNumber"),
        build_field_model("金额", "f_amount", "inputNumber"),  # 可能用于汇总
    ],
    render_key=0,
    show_summary=True,      # 显示汇总行
    summary_field="f_amount" # 汇总字段
)

子表格字段配置

子表格内的字段需要额外配置:

# 子表字段会自动设置 isSubTable 属性
# 但需要注意 parentVModel 和 relationTable
child_fields = [
    build_field_model("商品名称", "f_product_name", "input"),
    build_field_model("数量", "f_quantity", "inputNumber"),
]

workSystem 示例

表单名称 表单ID 子表配置
水电费用 585110234985398597 calculate + table, 自动计算
报价信息 585107422926864709 table, 商品明细
个人信息 585101489710563653 table, 教育经历等
采购合同 585077579715707205 table + calculate, 合同明细+金额计算
高级控件和默认查询 469499301635095045 table, 默认查询条件
订单示例 469133201755925637 table, 订单明细
采购管理 469106304141552773 table + uploadFile, 采购明细+附件
客户管理 469102214628043141 table, 客户联系人
OKR管理 469059874144184709 table, KR明细
报名管理外链 468848215723140933 table, 报名信息
应收费用 468826463014018501 table, 费用明细
产品管理 469039386000943493 table + modifyTime, 产品明细

高级配置

表格网格 (tableGrid)

一种特殊的子表格布局,支持主子表头。

{
  "__config__": {
    "jnpfKey": "tableGrid",
    "label": "费用明细",
    "tag": "JnpfTableGrid"
  },
  "children": [
    {
      "title": "项目",
      "children": [
        {"title": "名称", "dataIndex": "f_item_name"},
        {"title": "编码", "dataIndex": "f_item_code"}
      ]
    },
    {
      "title": "金额",
      "children": [
        {"title": "预算", "dataIndex": "f_budget"},
        {"title": "实际", "dataIndex": "f_actual"}
      ]
    }
  ]
}

workSystem 示例: 复杂表头(主子表)示例 (469496902811974149)

汇总行配置

# 汇总配置
table = build_table_field_model(
    label="订单明细",
    vmodel="f_order_detail_list",
    child_table_name="ord_order_detail",
    children=[...],
    show_summary=True,
    summary_field="f_amount"
)

新增弹窗配置 (addTableConf)

# 暂不支持,需手动配置
add_config = {
    "popupTitle": "新增明细",
    "popupWidth": "60%",
    "columnCount": 2  # 弹窗内字段排版
}

表格类型对比

类型 jnpfKey 说明 workSystem
子表格 table 嵌套表格 #25, #26, #27
表格网格 tableGrid 复杂表头主子表 #35

常见问题

问题 原因 解决
子表数据保存失败 isSubTable 未设置 子表字段必须使用 build_table_field_model
汇总不显示 show_summary 未设 show_summary=True
汇总字段不对 summary_field 错误 确认汇总字段名
弹窗新增失败 addTableConf 缺失 需要配置弹窗属性

数据存储规律

子表格存储规律

子表格(table)的数据存储在独立的物理表中,而非主表。

存储机制

  1. 主表字段:存储子表的外键关联(主键ID)
  2. 子表字段:存储在独立的物理表中,通过 f_flow_task_id 或 f_id 关联

子表数据结构

// 主表存储
{
  "f_id": "主表记录ID",
  "f_order_no": "SO20260407001",
  "f_order_detail_list": "811298790165190697"  // 子表关联ID
}

// 子表(ord_order_detail)存储
{
  "f_id": "子表记录ID",
  "f_flow_task_id": "811298790165190697",  // 关联主表
  "f_product_name": "产品A",
  "f_quantity": 10,
  "f_unit_price": 99.00
}

子表字段存储

子表内字段的存储与其他控件相同:

子表字段 存储类型 示例
input 字符串 "产品名称"
textarea 字符串 "备注信息"
inputNumber 数值/字符串 99.00 或 "99.00"
select/radio 字符串 "1"
checkbox JSON数组 ["1","3"]

数据库表结构要求

子表需要创建独立的物理表,表结构示例:

CREATE TABLE ord_order_detail (
    f_id VARCHAR(50) PRIMARY KEY,           -- 主键(雪花ID)
    f_flow_task_id VARCHAR(50),              -- 关联主表的flow_task_id
    f_product_name VARCHAR(200),             -- 商品名称
    f_spec VARCHAR(100),                     -- 规格型号
    f_unit VARCHAR(20),                       -- 单位
    f_quantity DECIMAL(18,2),                 -- 数量
    f_unit_price DECIMAL(18,2),               -- 单价
    f_amount DECIMAL(18,2),                   -- 金额
    -- 系统字段
    f_create_user VARCHAR(50),
    f_create_time DATETIME,
    f_modify_user VARCHAR(50),
    f_modify_time DATETIME
);

重要配置

配置 说明 必填
child_table_name 子表物理表名(snake_case) 是
children 子表字段列表 是
is_sub_table 标记为子表字段 自动设置
show_summary 是否显示汇总行 否
summary_field 汇总字段名 否

下一步