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

255 lines
6.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 子表格控件
## 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `table` |
| AIBridge builder | `build_table_field_model()` |
| 源码示例 | `extend/tableDemo/` 多种模式 |
| workSystem 示例 | 水电费用、报价信息、个人信息、采购合同 等 |
## 基本规则
### 核心概念
子表格是一种**嵌套表格**,用于在主表单中管理多条明细数据。
### 关键配置
| 配置 | 说明 | 必填 |
|------|------|------|
| child_table_name | 子表物理表名 | 是 |
| children | 子表字段列表 | 是 |
| show_summary | 是否显示汇总 | 否 |
| summary_field | 汇总字段 | 否 |
| addTableConf | 新增弹窗配置 | 否 |
| footerBtnsList | 底部按钮 | 否 |
| columnBtnsList | 列按钮 | 否 |
### AIBridge 使用
```python
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" # 汇总字段
)
```
### 子表格字段配置
子表格内的字段需要额外配置:
```python
# 子表字段会自动设置 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)
一种特殊的子表格布局,支持主子表头。
```json
{
"__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)
### 汇总行配置
```python
# 汇总配置
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)
```python
# 暂不支持,需手动配置
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` 关联
### 子表数据结构
```json
// 主表存储
{
"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"]` |
### 数据库表结构要求
子表需要创建独立的物理表,表结构示例:
```sql
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 | 汇总字段名 | 否 |
---
## 下一步
- [特殊控件](08-special-controls.md)
- [图表控件](09-chart-controls.md)
- [表格高级模式](10-table-patterns.md)