块编辑器功能设计

1. 功能状态

功能	当前状态	实现位置
文档加载	已实现	`editorStore`、`blockService`
标题和段落编辑	已实现	`HeadingBlock`、`ParagraphBlock`
富文本格式	已实现	`RichTextEditor`、`RichTextToolbar`
表格编辑	已实现	`TableBlock`、`TableToolbar`、`blockOperations`
图片上传和调整	已实现	`ImageBlock`、`imageUpload`
目录和大纲	已实现	`TOCBlock`、`DocumentOutline`
自动保存和重试	已实现	`editorStore`
Word 导出	已实现	`exportService`
PDF/Markdown 导出	已实现	`clientExportService`
块级拖拽排序	当前未提供	不应在文档中描述为已实现
协同编辑和版本回滚	未实现	需要独立设计
全文搜索替换	未实现	需要独立设计

2. 文档和块编辑

2.1 打开和加载

用户从聊天消息或导出记录打开文档后，前端根据文档 ID 请求 GET /api/v1/documents/{documentId}/blocks。返回的 blocks 按 block_order 排序后进入 editorStore。加载失败时编辑器显示错误状态并通过 Ant Design message 给出提示。

2.2 标题和段落

标题支持 H1 到 H6。
段落支持普通文本、有序列表和无序列表元数据；列表编号与标题编号彼此独立。
块菜单支持插入正文、标题、图片、表格、复制、移动和删除等操作。
Enter 可按当前格式创建后续块；有序列表按列表层级计算后续序号。
标题和段落都使用 RichTextEditor 编辑 RichText[]。

2.3 富文本

当前支持加粗、斜体、下划线、删除线、文本颜色、字号、字体和段落对齐。选中文本时显示浮动工具栏；工具栏使用 click 展开，入口显示和保持悬停由编辑器区域统一管理。颜色弹层支持外部点击、Escape 和离开相关区域关闭。

表格单元格不显示普通浮动工具栏，表格结构操作使用 TableToolbar。

3. 表格功能

3.1 结构操作

表格支持插入和删除行列、合并选中的视觉单元格、拆分横向/纵向/混合合并单元格、拖拽调整列宽和行高、单元格内容、文本样式和垂直对齐。

表格使用原生 table、tr 和 td 渲染。由于合并单元格会占据视觉网格中的多个位置，结构更新必须经过 getTableVisualCellPositions 和重建函数，不能直接对原始数组做简单 splice。

3.2 数据约束

interface TableCell {
  text: string | RichText[];
  rowspan: number;
  colspan: number;
  style: CellStyleOverrides;
}

隐藏单元格使用 rowspan: 0 或 colspan: 0 表示，不应在渲染层直接删除后再猜测其位置。

4. 图片功能

支持 JPG、PNG、GIF、WebP 和 BMP。
单个文件最大 10 MB。
最大边长 10000 像素，总像素数不超过 4000 万。
图片以 Data URL 存储在 block content 中。
支持替换、删除、左右/居中对齐和宽高调整。
渲染时预留宽高比例，使用 lazy loading 和 async decoding。

上传前检查文件类型和大小，读取后再次检查图片真实尺寸，避免仅依赖文件扩展名。

5. 保存行为

编辑操作先更新 Zustand 内存状态：

updateBlock
  -> dirtyBlocks
  -> hasModified
  -> 自动保存计时器
  -> 按块保存并发限制

默认自动保存延迟为 3 秒。工具栏提供自动保存/手动保存切换。关闭存在未保存修改的文档时会要求确认。网络失败的块会记录到 failedBlocks，可通过重试流程再次保存。

6. 导出

格式	方式	说明
Word	后端 API	生成导出记录后下载文件
PDF	浏览器动态加载库	截取 `.block-canvas` 并生成 PDF
Markdown	浏览器生成 Blob	按 block 顺序转换标题、段落、表格和图片

导出入口位于 MainToolbar。Word 导出需要有效的文档 ID；PDF 导出需要当前页面存在编辑器画布。

7. 当前明确不支持

以下内容不能作为当前产品能力对外承诺：多人实时协同编辑、版本历史和回滚、块级拖拽排序、全文搜索和替换、浏览器端真正安全的 API 密钥保护。实现这些功能前，应先补充数据协议、权限模型、状态冲突策略和测试方案。

新编辑器功能设计.md 5.0 KB Előzmények Nyers