canvas-table-integration

canvas-table-integration

仅将此技能用于 @qfei-design/canvas-table 的消费端集成。此技能不支持将 Ant Design Table、Arco Table、TDesign Table、原生 HTML 表格或任何其他表格实现用作产品表格。

此技能包含两条基础路径和一项可选增强：

• 路径 A 基础方案：非 Make 的本地／虚拟表格、公共 API、行头操作、可选的选择／拖拽／汇总，以及轻量级画布交互。
• 路径 C 基础方案：Make 架构驱动的列、共享的宿主字段显示注册表（位于 apps/ui/src/lib/make-field-types.ts 或宿主等效位置）、纯值规范化、字段渲染器，以及仅在溢出时显示的工具提示。
• 路径 B 增强方案：在选定的基础路径上添加单元格编辑，包括 customEdit、受控提交、弹出层所有权、宿主字段编辑器和回滚。

所有 Make 架构表格都选择路径 C 作为基础；只有在列不是由 Make 架构驱动时才选择路径 A。仅当明确要求编辑或已确立编辑功能时，才添加路径 B。路径 B 绝不取代选定的显示基础路径。

路径 B 硬性规则：所有 CanvasTable 单元格编辑实现都必须遵循路径 B 及 references/make-cell-edit-defaults.md。非弹出式编辑器只能保留 CanvasTable 的活动编辑边框；内部控件必须填满单元格且不显示边框。未能立即打开弹出层、在滚动后重新定位、规范化值或跳过未更改值的保存，均属于阻止就绪的问题。

快速开始

1. 确认这是消费端表格集成，而不是表格库维护工作。
2. 检查软件包安装情况，并按下方要求的顺序阅读软件包 AI 文档。结合业务行颜色与选择或悬停功能的集成，必须依赖已发布的 @qfei-design/canvas-table@^1.3.1 契约。
3. 选择基础轨道 A 或轨道 C。需要编辑功能时，添加轨道 B 作为增强；对于可编辑的 Make schema 表格，使用轨道 C 加轨道 B。
4. 对于 Make schema 表格，在初始化表格之前加载并规范化 schema 字段；根据规范化后的字段类型、schema field.properties 以及共享字段类型注册表构建 IColumn[] 和渲染器。桌面端和 tablet 端的字段标题还会通过公开的 prefixRender API 显示默认的 Lucide 类型图标；具体映射请参阅 makeui 的字段类型图标契约。
5. 只阅读主题映射中基础轨道的参考资料；如果包含编辑功能，再阅读轨道 B 的参考资料。
6. 有软件包配方或示例时，从中着手，再以最小的项目本地改动进行调整。
7. 除非用户明确选择关闭，否则启用表格行默认功能：使用 showSN 显示序号，并通过 bodyRowHeadSuffixOptions 添加悬停时显示的打开详情操作。
8. 对每个可写的 Make 记录列表，启用多选，并将默认的编辑、删除和批量编辑操作工作流路由到 make-app-actions。只有明确设为只读的列表才可关闭此功能。
9. CanvasTable 1.3.1 发布了业务行颜色契约：显式设置的 setRowColors / rowStyleOptions 颜色会在选择和悬停状态下保持可见；调用 clearRowColors 后，会恢复底层行样式或内置背景。使用该路径前，先解析 ^1.3.1；不得使用宿主 CSS 或私有导入来修复旧版软件包的渲染顺序。
10. 对于 Make schema 表格，应用平台字段渲染器默认设置。包含文本的溢出内容必须显示省略号；仅当溢出内容被省略或 +N 内容被隐藏时，才默认启用工具提示；不得要求用户提出此需求。
11. 对象、实体或 schema 键发生变化时，重置表格交互状态和滚动位置。不得将上一个对象的横向或纵向滚动位置带到下一个对象。
12. 表格初始化不得依赖行数：容器尺寸以及 schema/列准备就绪后创建表格，再在本地模式下通过 setData(latestRows) 应用最新行数据。在虚拟模式下，根据已安装的公开文档选择仅分页或身份感知回调，并遵守其分页/请求契约。空行数据仍然有效，必须继续渲染表头和空状态。
13. 对于大数据量、快速滚动或拖动滚动条时的虚拟加载，请遵循 references/virtual-table-patterns.md；该路径必须满足以下交付要求：选择已安装契约、请求身份管理、有界调度、取消过时请求、释放待处理页、原子化写入总数/页码，以及限制缓存大小。
14. 如果包含轨道 B，在完成前验证强制性的单元格编辑标准；非标准单元格编辑器不能作为可交付的部分结果。
15. 仅添加用户当前明确需要的功能。分页、排序、分组和单元格编辑均为可选；Make 记录列表选择操作默认通过 make-app-actions 启用。
16. 如果用户要求表头排序，仅使用本 Skill 说明的表头菜单/后缀机制，并将排序行为、openWithField、Preset 和记录时序交由 make-app-sort 处理。
17. 如果用户要求 Make 记录列表分组，仅使用本 Skill 说明的 GroupTableComponent 公开 API 机制，并将分组行为、Preset、record-groups、groupFilter 和叶级分页时序交由 make-app-group 处理。
18. 完成前，阅读相关的常见问题参考资料，并验证一条具体的表格路径。

不要将此技能用于

• 发布 @qfei-design/canvas-table
• 编辑表格库本身
• 生成或保留另一个产品表格实现，而不是使用 @qfei-design/canvas-table
• 维护表格库仓库内的 package.ai.json、recipes.json、示例或文档
• 配置私有 npm registry
• 将分组表格架构视为默认方案
• 在项目已有编辑器／组件系统的情况下，强行为其引入新的 UI 组件库
• 设计或生成 Make DSL YAML；请使用 makedsl 进行 schema 建模
• 设计 Service 路由、服务端断开连接处理或下游取消适配器；请使用 make-app-service

开始前检查

编辑代码前：

1. 确认当前项目已安装 @qfei-design/canvas-table。
2. 如果没有 package.json，请停止并告知用户当前目录不是 npm 包。
3. 如果缺少该包，根据 lockfile 检测包管理器，并在继续前安装：
   • pnpm-lock.yaml：
     • Make App：对于新建 App 或明确的运行时迁移，先验证 make-app-runtime 基线 "packageManager": "[email protected]"、Node.js 22.20.0 和 Corepack 0.34.0，然后运行 corepack pnpm add @qfei-design/canvas-table。对于现有 Make App，保留其声明的运行时，并使用 Corepack 解析其声明的 pnpm 版本；不要仅为了添加 CanvasTable 而迁移运行时。
     • 非 Make pnpm 项目：运行 pnpm add @qfei-design/canvas-table，并保留项目现有的包管理工作流；不要仅为了此次集成而引入 Corepack。
   • yarn.lock → yarn add @qfei-design/canvas-table
   • package-lock.json → npm install @qfei-design/canvas-table
4. 如果没有 lockfile：
   • Make App：新建 App 或明确的运行时迁移必须先建立 make-app-runtime 基线，然后运行 corepack pnpm add @qfei-design/canvas-table。对于没有 lockfile 的现有 Make App，请停止，并将包管理器、工作区以及 CI／安装工作流的协调交由 make-app-runtime 处理；不要假定使用 pnpm、生成 lockfile，也不要仅为了添加 CanvasTable 而迁移运行时。
   • 非 Make 项目：默认运行 npm install @qfei-design/canvas-table。
5. 如果安装失败，请停止并报告命令和错误。

请始终使用 @qfei-design/canvas-table。如果现有代码库使用了不同的包名，请停止并在更改使用方应用的依赖前征求确认。

如果现有 Make 记录列表使用了其他表格组件，预期的集成目标仍然是 @qfei-design/canvas-table。除非用户明确说明此页面不在 canvas-table 的范围内，否则不要保留 UI 库的表格作为主要记录表格。

必需的读取流程

1. 定位已安装包的根目录，或 package.json 中名称为 @qfei-design/canvas-table 的源包根目录。
2. 首先读取 <package-root>/package.ai.json。
3. 解析 package.ai.json.readOrder，将每个条目解析为相对于包根目录的路径，并验证其中声明的每个文件都存在。
4. 按声明的顺序读取其余条目，跳过已读取的 package.ai.json 条目。

package.ai.json.readOrder 是唯一可信来源。不要对 docs/、examples/、monorepo 文件夹名称或其他包内部文档路径进行硬编码。如果声明的文件缺失，请报告确切路径和包版本，不要根据内部源代码推断。

主题参考索引

任务 / 主题	阅读
公共属性、方法、事件、设置、清理	references/core-props-methods-events.md
行首序列号或打开详情操作	references/row-head-action-patterns.md
设置记录列表的默认选择以及编辑／删除／批量编辑操作	使用 make-app-actions
虚拟加载、分页后端集成、大数据快速滚动或拖动滚动条	references/virtual-table-patterns.md
Schema／meta 转换为 IColumn[]	references/column-patterns.md
普通表头和分组表头前的默认 Make 字段类型图标	makeui 字段类型图标约定 加上 references/column-patterns.md
自定义可点击单元格形状	references/shape-render-patterns.md
Track A 常见问题	references/common-pitfalls.md
单元格编辑约定	references/edit-contract.md
宿主侧编辑架构	references/edit-host-architecture.md
编辑生命周期、定位、关闭／提交／回滚	references/edit-interaction-lifecycle.md
平台 Make 可编辑单元格默认行为	references/make-cell-edit-defaults.md
字段编辑器映射	references/field-editor-patterns.md
宿主组件选择	references/editor-component-selection.md
附件编辑器集成	references/attachment-editor-patterns.md
Track B 常见问题	references/edit-common-pitfalls.md
Make 字段显示	references/make-field-display-patterns.md
已验证的下游用法和未验证区域	references/validated-usage-notes.md
Track 工作流、能力检查清单、输出模板	references/track-workflows.md
表头升序／降序行为、共享排序面板、Preset 和记录排序	使用 make-app-sort
Make 记录分组、Preset 分组、record-groups、groupFilter、分组叶节点分页	使用 make-app-group
服务路由取消、服务端断开连接处理、下游 AbortSignal 传播	使用 make-app-service

基础 Track A

按需阅读：

• references/core-props-methods-events.md
• 添加图标或操作到正文行首／序列号区域时，阅读 references/row-head-action-patterns.md
• 使用分页虚拟加载时，尤其是处理大量数据、快速滚动或拖动滚动条时，阅读 references/virtual-table-patterns.md
• 设置列时，阅读 references/column-patterns.md
• 添加自定义可点击单元格内容时，阅读 references/shape-render-patterns.md
• 定稿前阅读 references/common-pitfalls.md

基础 Track C

阅读：

• references/make-field-display-patterns.md
• 添加画布形状时，阅读 references/shape-render-patterns.md
• 根据字段 Schema 派生 IColumn[] 时，阅读 references/column-patterns.md
• 定稿前阅读 references/common-pitfalls.md

为单元格编辑添加 Track B

按以下顺序阅读：

1. 所选基础 Track 的参考文档；Make Schema 可编辑表格必须保留 Track C 的显示基线
2. package.ai.json.readOrder 声明的包级单元格编辑文档
3. references/edit-contract.md
4. references/edit-host-architecture.md
5. references/edit-interaction-lifecycle.md
6. references/make-cell-edit-defaults.md
7. references/field-editor-patterns.md
8. references/editor-component-selection.md
9. 涉及附件字段时，阅读 references/attachment-editor-patterns.md
10. 定稿前阅读 references/edit-common-pitfalls.md

如果缺少任何必需的包文件，请停止并准确告知用户缺少哪个文件。

轨道组合

• 轨道 A 和轨道 C 是互斥的显示基础。
• 轨道 B 是增强层，而不是替代基础。
• 非 Make 可编辑表格使用轨道 A 加轨道 B。
• Make 架构可编辑表格使用轨道 C 加轨道 B，以便在添加编辑功能的同时，保留显示规范化和渲染器行为。
• 详细工作流、能力清单和字段分组见 references/track-workflows.md 和 references/make-field-display-patterns.md。

安全规则和默认值

将以下内容视为安全规则：

• 仅限浏览器／客户端；绝不在 SSR 期间实例化
• 使用具有明确宽度和高度的真实 DOM 容器
• 仅使用文档说明的公共 API
• 绝不从 src 或 dist 导入
• 产品表格使用 @qfei-design/canvas-table；不要用 UI 库表格替代
• 使用 table.tableId 作为 globalEventBus.onWithNamespace(...) 的命名空间键
• 卸载／清理时销毁表格实例
• 切换对象／实体／架构路由时重置滚动位置和临时表格状态。对于 /objects/:objectKey，复用同一个 React 组件是可以的，但前提是表格以该标识为键，或者集成代码明确在标识变更时重置 canvas-table 实例／状态
• 绝不将原始 meta 直接传入表格运行时
• 创建表格前，将 meta 转换为 IColumn[]
• 对 Make 架构表格，在等待架构时，不要使用通用占位列或根据行键推断出的列来创建表格
• 不要使用 records.length、rows.length 或业务总数作为创建表格的门槛。空行是有效的表格状态：保留可见表头，并在调用 setData([]) 后显示内置空状态
• 如果行数据可能在 CanvasTable 实例就绪前到达，请存储最新行数据，并在实例创建后立即调用 setData(latestRows)；不要因 tableRef.current 为 null 而丢失早到的数据更新
• 绝不将数字解析失败渲染为 NaN、Infinity 或异常文本；在画布渲染前将其规范化为空显示值
• 绝不将格式化后的货币或百分比文本作为常规后端约定。包含 ¥、￥、% 或千位分隔符的字符串属于依赖缺陷；应渲染 - 或指出数据约定问题，而不是默默将其当作 API 就绪值处理
• 对 Make 架构表格，在生成的列／编辑配置中保留规范化后的 field.properties，以便渲染器和编辑器使用 Number.precision、Date.format、DateRange.begin/end、Currency.symbol/decimalPlaces/useGrouping、Percent.decimalPlaces、File.maxCount 和多重身份的 maxCount
• 数字、货币和百分比单元格编辑器必须保留原始的纯十进制输入文本，并在解析和提交前校验 Number.precision、Currency.decimalPlaces 或 Percent.decimalPlaces。小数位超限时，编辑器应保持激活状态，通过工具提示或外部校验界面显示 最多保留 N 位小数，且不得调用保存 API；除非宿主项目有明确文档说明，否则禁止静默舍入
• 数字单元格编辑器在无效的 IME 输入法组合期间必须保留最后提交的数字；按 Enter 选择尚未完成的 IME 候选项时，不得提交单元格。请遵循 references/field-editor-patterns.md 中的数字编辑器行为和验证指南
• 不要在可视化 canvas-table 宿主上，或任何可能包含程序包创建的可聚焦 canvas 的祖先元素上设置 aria-hidden 或 inert
• 如果需要屏幕阅读器回退表格，请将其保留为单独的视觉隐藏结构，并为可视化宿主提供独立且未隐藏的可访问标签
• 分页为可选功能：除非用户明确要求分页、虚拟加载或分页后端集成，否则不要添加可见分页控件、每页行数选择器、页码状态、分页查询参数、总数处理、分页获取逻辑、virtualOptions 或 data:load 连接
• 当已安装的文档提供虚拟分页请求上下文时，应同步认领该上下文，并将同一个请求传递给网络信号以及 setData／setVirtualPageData 或 markPageLoadFailed；仅当已安装版本的公共约定为旧版分页模式时，才使用仅包含页码的旧版路径
• 虚拟加载失败和取消时，必须通过已安装程序包文档说明的公共 API 释放程序包的待处理分页标记；大数据或快速滚动路径还必须使用有界宿主调度器，而不是立即触发每个临时视口分页请求
• 排序为可选功能：仅在用户要求时，通过宿主文档说明的 CanvasTable 表头菜单／后缀 API 提供表头升序／降序操作，然后调用共享的 make-app-sort 控制器。不要在本地对记录排序、单独维护表头排序状态，或从表头操作直接调用 records
• 分组为可选功能：对于 Make 记录列表，使用 make-app-group 处理程序包面板、Preset、Service、groupFilter 和 records 时序。此 Skill 可以实例化 GroupTableComponent 并连接 group:load／group:data:load，但不得自行定义分组语义
• Make 记录操作为默认功能：此 Skill 负责连接公共选择快照、clearSelection、受支持的 Shift／全选行为和行颜色；make-app-actions 负责操作状态、权限、预检、批量模态框和变更时序。根据 CanvasTable 1.3.1 约定，GroupTableComponent 不支持 Shift 范围选择；不要在宿主中模拟此行为
• 将 CanvasTable 1.3.1 的语义行颜色优先级和清理行为视为记录操作契约的最低要求：业务行颜色必须在选择和悬停状态之上保持可见；命令颜色必须通过文档说明的 clearRowColors(rowKeys) 移除。setRowColors(rowKeys, undefined) 不是清理备用方案。要求使用 @qfei-design/canvas-table@^1.3.1，而不是在宿主中覆盖 canvas 内部实现
• 对普通 Make CanvasTableComponent 记录列表，一次 Shift 范围选择手势最多可选择 200 条记录。仅通过已安装的公共选择约定执行此限制；如果缺少此功能，请报告阻塞问题，而不是实现宿主键盘锚点、范围扩展或私有选择状态

详细工作流和维护参考

• 如需了解轨道工作流、能力清单、避用清单、暂缓处理的主题和最终回复模板，请阅读 references/track-workflows.md。
• 使用当前项目或软件包文档未明确涵盖的能力前，请阅读 references/validated-usage-notes.md，以区分已验证的下游模式与尚未充分验证的软件包能力。