Acheron Grid 集成指南 — TypeScript、Canvas 与 AI

1. 从源码构建

包尚未发布到 npm。请使用 Node.js 22 或更高版本和仓库检出副本。

git clone https://github.com/haodn-dev/acheron-grid.git
cd acheron-grid
npm ci
npm run build
npm run playground

在独立应用中，通过包管理器从本地路径安装已构建的包。

npm install /path/to/acheron-grid/packages/core /path/to/acheron-grid/packages/canvas

TypeScript coreState · commands · history

CanvasDrawing · editors · input

React / Vue / TSApplication · lifecycle

无界面 TypeScript 核心管理状态和命令。Canvas 负责单元格绘制和输入，React、Vue 或原生 TypeScript 将表格连接到应用。

2. 挂载网格

容器宽高必须大于 0。使用稳定行 ID 和明确列键。

import { LocalDataSource } from '@acheron-grid/core';
import { createGrid } from '@acheron-grid/canvas';

const source = new LocalDataSource([
  { id: 1, title: 'Hello grid' }
], row => row.id);
const grid = createGrid({
  container: document.querySelector('#grid'),
  columns: [{ key: 'title', title: 'Title', editable: true }],
  dataSource: source
});
// On unmount:
grid.destroy();

3. 配置交互

使用列解析器验证输入，分别设置编辑、选择、剪贴板和格式权限。单元格渲染器接收值与格式元数据，选项渲染器接收列键。

编辑： Enter 或 F2 打开文本或选项编辑器；Enter 切换复选框。
格式： Ctrl/Cmd+B 和 I 格式化所选单元格；富文本编辑时格式化所选文字。
链接： 悬停或选择单元格可显示每个安全链接的快捷入口。
结构： 选择整行或整列，通过可用菜单重排、插入或删除。
富文本： HTML 转换为安全文本片段，Markdown 使用可选解析适配器。

参阅 Canvas 包文档了解完整选项。仓库默认分支可能与本地预览不同。

编辑器与验证

保存或粘贴前使用列解析器验证文本。抛出明确错误可保留草稿供用户修正。API 更新接收已验证的值，不运行列解析器。

columnEditors: {
  priority: { type: 'select', values: ['High', 'Medium', 'Low'] },
  tags: { type: 'multiselect', values: ['Idea', 'Design', 'Content'] },
  approved: { type: 'checkbox' }
},
choiceEditor: { placeholder: 'Find an option…', maxHeight: 220 },
multilineEditor: true,
wrapText: true,
editorOptions: { pinned: true, showLabel: 'scroll', guardNavigation: true }

创建网格时与 columns 和数据源一起设置。多选以逗号分隔字符串存储，标签不能含逗号。上下键导航，Space 切换，Enter/Apply 保存，Escape/Cancel 取消。选项和单元格渲染器应共享配色。

体验编辑与验证 ↗

选择与剪贴板

单击与 Shift 单击选择矩形，Ctrl/Cmd 单击添加区域。行号与分组表头选择整个范围。Shift+Space 选行，Ctrl/Cmd+Space 选列，Shift+F10 打开支持输入筛选的菜单。

grid.selectRow(0);
const tsv = grid.copySelection();
grid.paste(tsv);

粘贴先验证所有目标、权限和解析器，再以原子命令应用，不会创建缺失行。TSV 只交换数值，内部剪贴板与结构化 API 可保留富文本样式和区域偏移。不能假定外部应用保留相同格式。上限为 100,000 个单元格及一千万 UTF-16 单位。

体验选择与键盘 ↗

数值、事件与历史

grid.updateCells([
  { rowIndex: 0, columnKey: 'title', value: 'Lorem ipsum' }
]);
grid.undo();
grid.redo();

使用稳定行 ID 和列键。LocalDataSource 支持同步原子批量，自定义源多单元格写入需要原子 setValues。数值、格式、显式尺寸与冻结、结构命令共享有限历史。锁定和自动行测量不计入用户历史。重放会重新检查策略并可能拒绝冲突的外部更改。

使用 onEvent 观察已提交的领域事件，例如 cell:change 和 structure:change。通知不会回滚已提交变更。直接写入源会绕过历史，持久化由应用负责。

搜索、排序与筛选

grid.openSearch();
grid.setView({
  sort: { columnKey: 'title', direction: 'asc' },
  filters: [{ columnKey: 'title', operator: 'contains', query: 'Lorem' }]
});
grid.setView({});

搜索高亮显示文本。本地视图按一列排序，以 AND 组合筛选，支持 contains、equals、not-empty、empty。提供 onViewChange 时还须设置 viewMode: 'core' 以保留状态。公开行坐标按显示顺序，权限解析及非选择领域事件使用源坐标和稳定 ID。

结构操作前清除视图，排序筛选前移除合并和分组。内存筛选排序成本仍随源大小增长。

体验搜索、排序与筛选 ↗

分组表头、冻结与尺寸

headerGroups: [{ title: 'Availability', children: [
  { title: 'Channels', children: ['online', 'onsite'] },
  { title: 'Delivery', children: ['shipping'] }
] }],
headerHeight: 28,
autoRowHeight: true,
wrapText: true

列保持扁平定义，分组叶列须唯一、连续且按列顺序排列。headerHeight 表示每层表头高度，选择子列时祖先表头也会着色。

grid.setFrozen(1, 1);
grid.setColumnWidth(1, 240);
grid.setRowHeight(0, 64);

冻结数量不含表头和行号。调整尺寸时预览引导线，松开后应用。自动适配使用可见内容，自动行高测量可见行的全部列。手动尺寸优先，过大的冻结区域可能占满视口。

体验表头、冻结与尺寸调整 ↗

结构、合并与行分组

通过 onReorder 启用拖动并使用公开 API 应用移动。beforeIndex 为移除前的插入边界，宿主通过 onRowChange 创建行 ID 和默认值，allowColumnChanges 启用内置列创建删除菜单。

onReorder: request => {
  if (request.axis === 'row') grid.moveRows(request.indices, request.beforeIndex);
  else grid.moveColumns(request.indices, request.beforeIndex);
}

回调在挂载后且 grid 可用时执行。canChangeStructure 策略检查同时适用于命令和历史重放。分组列须保持连续。

grid.mergeCells({ startRow: 2, endRow: 3, startColumn: 1, endColumn: 2 });
const groupId = grid.groupRows(3, 6);
grid.setGroupCollapsed(groupId, true);
grid.setGroupCollapsed(groupId, false);
grid.ungroupRows(groupId);

区域含结束端点。合并保留底层值以供取消合并，行分组是手动折叠结构而非聚合。不兼容结构变更前先展开分组并取消相交单元格合并。

体验行列操作 ↗ · 体验合并与分组 ↗

富文本、图片与安全链接

import { markdownToHtml } from '@acheron-grid/markdown';

// createGrid options:
richTextColumns: { notes: 'markdown', description: 'html' },
markdownToHtml,
imageColumns: ['avatar']

Markdown 适配器可选，核心和 Canvas 不依赖其解析器。用户看到格式化内容，宿主存储源字符串。HTML 支持下划线，Markdown 不添加下划线语法。Ctrl/Cmd+B 或 I 格式化编辑中的所选文字，或非编辑状态的所选单元格。

Canvas 只绘制受限文本片段，不挂载解析后的 HTML 或执行处理器；它不是用于将存储 HTML 插入其他 DOM 的通用净化器。可见图片以匿名 CORS 请求，尚无上传裁剪。悬停或聚焦链接单元格可显示安全 URL 快捷入口。

体验富文本与链接 ↗

权限、锁定与自定义

resolveCellPermission: cell => cell.rowId === 'protected'
  ? { writable: false }
  : undefined,
permissions: { formatting: false }

选择、复制、粘贴、编辑、写入和格式是独立权限。显式 false 在更具体作用域仍具有否决权。只读行可允许选择复制，动态策略更改需要 grid.render() 更新控件，编辑提交会重新验证策略。

grid.setLocked({ scope: 'row', rowIndex: 0 }, true);
grid.format([{ scope: 'column', columnIndex: 1 }], { background: '#fff0dd' });
grid.setTheme({ selectionColor: '#d44b21', iconColor: '#334155' });

锁定作用于单元格、行、列或表。解锁单元格不会解除相关行表锁，冻结只保持可见性而不禁止编辑。主题更新保留挂载，renderCell 和 createEditor 可定制呈现。渲染器须遵守所支持的格式字段，客户端策略不能替代服务器授权。

体验格式与权限 ↗

故障排查

网格为空： 检查容器尺寸、数据源行数、列键与浏览器控制台。
无法编辑： 检查 editable、解析器、setter、已解析权限和锁定。
Markdown 被拒绝： 提供同步 markdownToHtml 回调。
图片不可用： 检查 URL、CORS 和服务器响应。
移动或视图变更被拒绝： 检查活动草稿、视图、分组、合并及宿主策略。
无法撤销： 直接修改源与自动测量绕过用户历史。

宿主卸载时务必销毁网格。参阅完整 Markdown 实用指南及各包契约了解详细限制。

React 与 Vue

这些包 @acheron-grid/react 和 @acheron-grid/vue 管理 Canvas 挂载和卸载、类型化 ref 及核心事件转发。保持 options 稳定，通过运行时 props 更新主题、视图和冻结区域，无须重新挂载。

阅读 React 与 Vue Markdown 示例了解完整组件、peer 版本和生命周期约定。两个适配器在 SSR 时均渲染空容器，框架渲染位于无界面核心之外。

4. 与 AI 助手阅读

从公开文档索引开始，然后阅读 AI 集成说明。Markdown 包含具体示例与已实现功能的限制，不公开凭据或内部规划。

可选 MCP 适配器提供文档资源和宿主授权的读取、更新工具。参阅 MCP 参考了解 stdio 配置与限制。浏览器演示不会自动连接。

浏览五个包与 AI 说明 ↗

API 参考与深入示例

本指南涵盖常见流程。完整选项、方法、默认值、回调载荷和边界情况请参阅各包文档。

目前尚无自动生成且可搜索的 API 参考，也未为每个自定义渲染器和编辑器提供可运行示例。仓库文档版本可能与本地预览不同。

当前限制

这是实验性开发预览，尚不包含远程数据源、协作、公式或自动 MCP 浏览器桥接。演示更改仅保留在当前会话；虚拟化不会使内存筛选成本脱离数据规模。

采用 Hao Duong 的 MIT 许可，不宣称生产环境性能保证或无障碍认证。

从数据到可交互网格。