ax-frontend-app/docs/集成快速参考.md

编辑器集成快速参考

文档状态

本文档描述当前已经运行的块编辑器集成方式。项目不再通过 Feature Flag 在 MDXEditor 和 BlockEditor 之间切换，也不需要额外安装编辑器框架、拖拽库或虚拟滚动库。

当前调用链

App
  -> ResizableLayout
    -> ChatPanel
    -> ExportRecordList 或 EditorPanel
       -> EditorWithOutline
          -> BlockEditor
             -> MainToolbar
             -> BlockCanvas
                -> BlockRenderer
                   -> HeadingBlock / ParagraphBlock / TableBlock / ImageBlock / TOCBlock

打开文档的流程：

1. 聊天消息或导出记录触发文档预览。
2. uiStore 保存 previewDocumentId 和文档名称。
3. App.tsx 根据 previewDocumentId 切换右侧面板。
4. EditorPanel 将参数传给 EditorWithOutline。
5. BlockEditor 调用 editorStore.loadDocument 加载 blocks。
6. 用户编辑后由 store 标记脏块，自动保存或手动保存。

关键接口

import EditorPanel from './components/EditorPanel/EditorPanel';

<EditorPanel documentId={documentId} initialDocumentName={documentName} onClose={closeEditor} />;

EditorPanelProps：

属性	类型	说明
documentId	string	必填，后端文档 ID
initialDocumentName	string \| null	可选，优先作为工具栏标题
onClose	() => void	必填，关闭编辑器回调

只读场景可直接使用 BlockEditor，但当前 EditorPanel 默认使用可编辑模式。

已支持能力

• 标题、段落、有序列表和无序列表。
• 富文本加粗、斜体、下划线、删除线、颜色、字体和字号。
• 表格增删行列、合并/拆分单元格、单元格选择、列宽和行高调整。
• 图片上传、尺寸调整、对齐、替换和删除。
• 目录块和文档大纲导航。
• 自动保存、手动保存、未保存关闭确认、失败重试和请求取消。
• Word、PDF、Markdown 导出。

表格结构操作必须复用 src/utils/blockOperations.ts 的视觉坐标算法。不要直接按原始 cells 数组索引插入合并单元格，否则会破坏 rowspan 和 colspan 同时存在时的布局。

运行和验证

npm install
npm run dev
npm run build
npm run lint
npm run format:check

生产预览使用 npm run serve:prod。开发端口为 5173，生产预览端口为 4173。

维护边界

• 不要重新引入 MDXEditor、Slate、@dnd-kit 或 react-window，当前实现不依赖它们。
• 不要删除 EditorPanel 外壳，它仍由 App.tsx 动态加载。
• 不要在表格单元格中额外挂载普通浮动格式工具栏；表格使用结构工具栏和选区样式操作。
• PDF、截图和 Word 解析库必须保持动态导入，避免增大首屏资源。
• VITE_*_API_KEY 会进入浏览器构建产物，生产环境应使用后端代理。

相关文档

• 编辑器架构设计
• 编辑器功能设计
• 编辑器开发手册
• 实现路线图
• 聊天面板集成方案