AiCrudPage 表格增强与通用展开面板

status: propose created: 2026-06-27 complexity: 🔴复杂

1. 背景与目标

AiCrudPage 当前已承载低代码运行态、动态 CRUD 页面和页面模板渲染。列表区需要补齐更接近飞书多维表格的表格体验：列宽配置、列宽拖拽、固定头部、固定列，以及最重要的行展开能力。

行展开不能只理解为“展开一个子表”。业务上常见展开内容包括子表、描述信息、只读表单、多个分组、多个子表 Tab、自定义组件和插槽。目标是新增一个通用 expandConfig 协议，让用户在设计器里用低门槛配置展开内容，运行态按同一协议加载数据和渲染。

完成后的效果：

列宽、固定列、横向滚动、固定头部和列宽拖拽具备统一配置入口。
展开面板支持 table、descriptions、form、tabs、custom 等内容类型，不局限于表格。
子表展开可按当前行字段映射参数，懒加载子表数据并缓存。
设计器提供“展开面板”配置入口，用户优先通过选择子表/字段/组件完成配置，而不是手写 JSON。
运行态兼容现有 AiCrudPage 页面，没有配置展开时不改变原行为。

2. 代码现状（Research Findings）

2.1 相关入口与链路

forge-admin-ui/src/components/ai-form/AiCrudPage.vue
- 模板中通过 <AiTable> 渲染主列表，传入 tableColumns、dataSource、paginationConfig、computedMaxHeight、computedScrollX 和 tableProps。
- tableColumns 负责把 props.columns 转为运行态列，并补默认操作列。
- computedScrollX 会按列 width/minWidth 自动计算横向滚动宽度。
- computedMaxHeight 默认返回 calc(100vh - 280px)，已经为固定表头提供基础。
forge-admin-ui/src/components/ai-form/AiTable.vue
- 是 n-data-table 的封装，主表通过 v-bind="$attrs" 透传部分 Naive UI 属性。
- 内部再次转换列，当前保留了 width/minWidth/maxWidth/fixed/ellipsis/sorter/filter 等列属性。
- 当前未显式管理展开行、列宽拖拽后的宽度状态和展开内容渲染。
forge-admin-ui/src/components/ai-form/AiCrudPageProps.js
- 已定义 columns、maxHeight、scrollX、tableProps、childrenConfig 等 props。
- childrenConfig 当前用于新增/编辑/详情中的 ChildTableEditor，不是列表行展开能力。
forge-admin-ui/src/components/page-templates/MasterDetailCrudTemplate.vue
- 主子表模板把 childrenConfig 注入 AiCrudPage，用于表单/详情里的子表编辑。
- 可复用子表配置来源，但不能直接等同于列表展开面板。
forge-admin-ui/src/views/app-center/components/designer/BusinessListDesigner.vue
- 构造运行态 crudProps，已经传递 maxHeight、scrollX、tableSize、bordered、striped、hideSelection 等列表配置。
forge-admin-ui/src/components/lowcode-builder/page/ListPageGridDesigner.vue
- AiCrudPage 属性面板已有“查询与列表字段”配置区，包含字段排序、列宽、对齐、固定、最大高度、横向宽度等语义。
- 适合作为新增“展开面板”配置入口。

2.2 现有实现

列宽：列配置已可带 width/minWidth/maxWidth，AiTable 会传给 Naive UI。
固定列：列配置已可带 fixed，默认操作列固定在右侧。
固定头部：AiCrudPage 默认传 maxHeight，Naive UI 在有 max-height 时可固定表头。
横向滚动：AiCrudPage 支持 scrollX，未传时按列宽自动计算。
主子表：已有 childrenConfig + ChildTableEditor，但用于表单区域，不用于主表行展开。

2.3 发现与风险

展开行属于数据加载和渲染协议，不能只作为 tableProps 透传给 n-data-table，否则低代码设计器、运行态、预览和生成器无法统一。
childrenConfig 可以作为“推荐子表来源”，但展开面板要支持描述、表单、Tabs 和自定义组件，不能命名成 childTableExpandConfig。
列宽拖拽分为设计态和运行态两种语义：设计态应写回 schema；运行态可先本地状态，后续再保存到用户偏好。
固定列依赖列宽和 scrollX，设计器需要引导或自动补默认宽度。

3. 功能点

表格基础增强：支持列宽、最小宽、最大宽、固定列、固定头部、横向滚动的统一配置和运行态映射。
列宽拖拽：支持通过 tableProps.resizable 开启列宽拖拽，拖拽后更新运行态列宽状态；设计态可写回 schema。
展开开关：支持 expandConfig.enabled 开启主表行展开。
展开数据源：支持按当前行映射参数懒加载 API 数据，也支持直接读取当前行嵌套字段。
展开内容类型：支持 table、descriptions、form、tabs、custom。
子表展开：支持从 childrenConfig 或低代码模型关系中选择子表，自动生成展开表格列和参数映射。
描述展开：支持选择字段，以多列描述信息展示当前行详情或远程详情。
表单展开：支持复用 AiForm 只读渲染字段，适合复杂字段布局。
Tabs 展开：支持一个展开区域内配置多个面板，例如“明细 / 流程 / 附件 / 日志”。
自定义展开：支持插槽或组件 key，给复杂业务保留逃生口。
设计器入口：在 AiCrudPage 属性面板新增“展开面板”配置，提供常用预设，不要求用户手写 JSON。
预览与发布：低代码预览、运行页和动态 CRUD 页面都按同一 expandConfig 渲染。

4. 业务规则

expandConfig 是 AiCrudPage 的一级配置，不放入普通列配置中。
未配置 expandConfig.enabled=true 时，现有列表行为不变。
展开面板默认懒加载，首次展开请求数据；cache=true 时同一行重复展开复用缓存。
展开数据请求参数通过表达式映射当前行，例如 orderId: row.id、tenantId: row.tenantId。
展开内容支持多类型，但第一期必须优先保证 table、descriptions、tabs 可用。
table 展开内的子表默认不显示工具栏，不显示多选，不启用行操作，除非显式配置。
固定列必须具备明确宽度；未配置时运行态可自动补默认宽度并在设计器提示。
列宽拖拽不能破坏列显示/隐藏、列排序和自定义查询结果展示。

4.1 推荐配置协议

expandConfig: {
  enabled: true,
  trigger: 'icon', // icon | row | both
  lazy: true,
  cache: true,
  defaultExpanded: false,
  rowExpandable: {
    type: 'expression',
    expression: 'row.hasDetail != false'
  },
  panels: [
    {
      key: 'items',
      title: '明细',
      type: 'table',
      dataSource: {
        type: 'api',
        api: 'get@/api/order/item/page',
        method: 'get',
        paramsMap: {
          orderId: 'row.id'
        },
        dataField: 'records',
        totalField: 'total'
      },
      table: {
        rowKey: 'id',
        columns: [
          { prop: 'productName', label: '商品名称', width: 180 },
          { prop: 'quantity', label: '数量', width: 100 },
          { prop: 'amount', label: '金额', width: 120 }
        ],
        pagination: false,
        maxHeight: 320
      }
    },
    {
      key: 'summary',
      title: '概览',
      type: 'descriptions',
      dataSource: {
        type: 'row'
      },
      descriptions: {
        columns: 3,
        fields: [
          { field: 'customerName', label: '客户' },
          { field: 'statusName', label: '状态' },
          { field: 'remark', label: '备注', span: 3 }
        ]
      }
    }
  ],
  layout: {
    mode: 'tabs', // single | tabs | stack
    density: 'compact',
    padding: 12
  }
}

4.2 面板类型

type	展示形式	数据来源	典型场景
`table`	内嵌表格	API / row 字段 / 子表关系	订单明细、项目成员、附件列表
`descriptions`	描述列表	row / detail API	飞书式展开概览、关键字段补充
`form`	只读 AiForm	row / detail API	复杂字段分组、布局化详情
`tabs`	多 Tab 容器	子 panels	多个子表或“明细+日志+流程”
`custom`	插槽/组件	row + dataSource	特殊业务卡片、图表、时间线

5. 数据变更

操作	表名	字段/索引	说明
无	-	-	本变更优先使用现有页面 schema/config JSON 扩展，不新增数据库表字段。若后续运行态列宽需按用户持久化，可另开用户偏好配置变更。

6. 接口变更

操作	接口	方法	变更内容
复用	子表/详情接口	GET/POST	展开数据源复用已有 CRUD/detail/list 接口，通过 `paramsMap` 传当前行参数。
无强制新增	-	-	AiCrudPage 不强制后端新增统一展开接口。低代码运行态如需子表数据，可由发布流程生成或复用已有运行态 API。

7. 影响范围

forge-admin-ui/src/components/ai-form/AiCrudPage.vue
forge-admin-ui/src/components/ai-form/AiCrudPageProps.js
forge-admin-ui/src/components/ai-form/AiTable.vue
新增 forge-admin-ui/src/components/ai-form/AiCrudRowExpand.vue（建议）
新增 forge-admin-ui/src/components/ai-form/expand-renderers/*（建议）
forge-admin-ui/src/views/app-center/components/designer/BusinessListDesigner.vue
forge-admin-ui/src/components/lowcode-builder/page/ListPageGridDesigner.vue
forge-admin-ui/src/components/lowcode-builder/preview/LowcodePreviewPane.vue
forge-admin-ui/src/components/lowcode-builder/page/GridBlockRenderer.vue
低代码 schema 编译、预览、发布链路中 AiCrudPage props 透传逻辑

8. 风险与关注点

展开行请求可能造成 N+1 接口压力，必须懒加载并支持缓存。
展开面板内嵌表格再嵌套复杂组件时，表格高度、横向滚动和固定列容易产生布局冲突。
自定义查询、列筛选和列拖拽都操作列集合，需要明确列宽状态合并顺序。
卡片模式下是否展示展开能力需单独定义；第一期建议仅表格模式支持展开。
如果展开子表涉及权限和多租户，后端仍必须按现有鉴权、数据权限和租户规则处理，前端只负责参数传递。
不涉及资金、状态流转、权限放开。

8.5 测试策略

测试范围：前端组件单测/构建、设计器 schema 转换、运行态手工/E2E 验收。
覆盖率目标：核心配置归一化函数、参数映射函数、展开数据加载函数需要单测覆盖；组件渲染通过 E2E 覆盖主要场景。
独立 Test Spec：是，见 test-spec.md。

9. 待澄清

运行态列宽拖拽是否需要第一期持久化到用户偏好，还是只在当前页面会话生效。
展开面板第一期是否允许编辑子表，还是只读查看。建议第一期只读，编辑仍走详情/编辑弹窗里的 ChildTableEditor。
custom 类型组件来源是否限制在已注册组件白名单，避免任意组件 key 带来安全和维护风险。

10. 技术决策

展开能力命名为 expandConfig，不是 childTableConfig，避免限制在子表。
展开内容采用 panels[]，即使单面板也走同一结构，方便后续 tabs/stack 扩展。
子表展开优先使用懒加载，默认缓存每行展开结果。
第一优先级支持 table、descriptions、tabs，第二优先级支持 form、custom。
childrenConfig 只作为子表展开的配置来源之一，不替代 expandConfig。

11. 执行日志

Task	状态	实际改动文件	备注
方案沉淀	已完成	`spec.md`	本轮只记录方案，不改业务代码。

12. 审查结论

待实现后审查。

13. 确认记录（HARD-GATE）

确认时间：待确认
确认人：待确认

spec.md 12 KB Histórico Em bruto