# 编辑器集成快速参考

## 文档状态

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

## 当前调用链

```text
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 标记脏块，自动保存或手动保存。

## 关键接口

```tsx
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` 同时存在时的布局。

## 运行和验证

```bash
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` 会进入浏览器构建产物，生产环境应使用后端代理。

## 相关文档

- [编辑器架构设计](./新编辑器架构设计.md)
- [编辑器功能设计](./新编辑器功能设计.md)
- [编辑器开发手册](./新编辑器开发手册.md)
- [实现路线图](./新编辑器实现路线图.md)
- [聊天面板集成方案](./新编辑器与聊天面板集成方案.md)