236 lines
6.3 KiB
Markdown
236 lines
6.3 KiB
Markdown
|
# 统一编辑器设计（TipTap 单内核 + 双格式存储）
|
|||
|
|
|
|||
|
|
## 1. 背景与目标
|
|||
|
|
|
|||
|
|
当前项目存在两类编辑需求：
|
|||
|
|
|
|||
|
|
- `markdown`：知识文档等偏结构化内容
|
|||
|
|
- `html` 富文本：所见即所得编辑、IM 消息等
|
|||
|
|
|
|||
|
|
现状是不同场景存在分叉实现，维护成本高，交互也不一致。
|
|||
|
|
本设计目标是在不破坏现有后端接口（`contentType + content`）前提下，统一前端编辑器体系。
|
|||
|
|
|
|||
|
|
### 目标
|
|||
|
|
|
|||
|
|
- 统一编辑内核：前端所有编辑场景尽量使用 TipTap/ProseMirror
|
|||
|
|
- 兼容双格式：继续保留 `contentType = "markdown" | "html"`
|
|||
|
|
- 保持可演进：后续可扩展图片上传、草稿、快捷键、插件化工具栏
|
|||
|
|
- 降低迁移风险：分阶段替换，不一次性重写全部页面
|
|||
|
|
|
|||
|
|
### 非目标
|
|||
|
|
|
|||
|
|
- 不追求 markdown 与 html 的绝对无损双向转换
|
|||
|
|
- 不在第一阶段实现完整协作编辑（OT/CRDT）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 核心结论
|
|||
|
|
|
|||
|
|
可以使用 TipTap 作为单一编辑内核，但不建议把 markdown/html 简化为“完全等价格式”。
|
|||
|
|
|
|||
|
|
- TipTap 的内部模型是 ProseMirror 文档，不是 markdown AST
|
|||
|
|
- markdown 与 html 语义存在差异，复杂结构双向转换会有损
|
|||
|
|
- 正确做法是：**内核统一 + 存储分型 + 转换可控**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 总体架构
|
|||
|
|
|
|||
|
|
建议目录（以 `web/components/editor` 为中心）：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
web/components/editor/
|
|||
|
|
index.tsx # 统一入口组件 UnifiedEditor
|
|||
|
|
html.tsx # HtmlEditor（TipTap 配置）
|
|||
|
|
markdown.tsx # MarkdownEditor（TipTap markdown 模式）
|
|||
|
|
viewer.tsx # 统一只读渲染入口（可选）
|
|||
|
|
toolbar.tsx # 通用工具栏（可按能力裁剪）
|
|||
|
|
schema.ts # TipTap 扩展与能力分组
|
|||
|
|
convert.ts # markdown/html 与 editor doc 的转换封装
|
|||
|
|
sanitize.ts # HTML 白名单清洗（渲染前）
|
|||
|
|
types.ts # 统一类型定义
|
|||
|
|
DESIGN.md # 本文档
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 数据模型与接口
|
|||
|
|
|
|||
|
|
## 4.1 类型定义（建议）
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
export type EditorMode = "markdown" | "html"
|
|||
|
|
|
|||
|
|
export type EditorValue = {
|
|||
|
|
mode: EditorMode
|
|||
|
|
raw: string
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export type UnifiedEditorProps = {
|
|||
|
|
value: EditorValue
|
|||
|
|
onChange: (next: EditorValue) => void
|
|||
|
|
placeholder?: string
|
|||
|
|
disabled?: boolean
|
|||
|
|
features?: {
|
|||
|
|
image?: boolean
|
|||
|
|
link?: boolean
|
|||
|
|
table?: boolean
|
|||
|
|
codeBlock?: boolean
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
说明：
|
|||
|
|
|
|||
|
|
- `raw` 存放最终持久化内容（markdown 文本或 html 字符串）
|
|||
|
|
- 外层业务不再关心“用什么编辑器实现”，只处理 `value/onChange`
|
|||
|
|
|
|||
|
|
## 4.2 现有接口兼容
|
|||
|
|
|
|||
|
|
与当前后端接口保持一致：
|
|||
|
|
|
|||
|
|
- `contentType` <- `value.mode`
|
|||
|
|
- `content` <- `value.raw`
|
|||
|
|
|
|||
|
|
无需改后端数据结构。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 模式策略（重点）
|
|||
|
|
|
|||
|
|
## 5.1 html 模式
|
|||
|
|
|
|||
|
|
- 导入：`setContent(html)`
|
|||
|
|
- 编辑：TipTap 常规富文本
|
|||
|
|
- 导出：`editor.getHTML()`
|
|||
|
|
|
|||
|
|
## 5.2 markdown 模式
|
|||
|
|
|
|||
|
|
- 导入：`markdown -> editor doc`
|
|||
|
|
- 编辑：仍使用 TipTap 内核（可配置 markdown 友好的工具栏）
|
|||
|
|
- 导出：`editor doc -> markdown`
|
|||
|
|
|
|||
|
|
## 5.3 模式切换
|
|||
|
|
|
|||
|
|
当用户手动切换 `markdown/html` 时：
|
|||
|
|
|
|||
|
|
1. 弹出确认提示：告知可能发生格式损失
|
|||
|
|
2. 用户可选：
|
|||
|
|
- 仅切换模式（保留原始内容，不做转换）
|
|||
|
|
- 执行转换（尝试 markdown/html 互转）
|
|||
|
|
3. 转换失败时回退并提示错误原因
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 转换与边界规则
|
|||
|
|
|
|||
|
|
## 6.1 支持稳定转换的子集
|
|||
|
|
|
|||
|
|
第一阶段建议仅保证以下元素稳定：
|
|||
|
|
|
|||
|
|
- 段落、标题（h1-h3）
|
|||
|
|
- 粗体、斜体、删除线
|
|||
|
|
- 无序/有序列表
|
|||
|
|
- 引用
|
|||
|
|
- 行内代码、代码块
|
|||
|
|
- 链接
|
|||
|
|
- 图片（基本属性）
|
|||
|
|
|
|||
|
|
## 6.2 明确有损边界
|
|||
|
|
|
|||
|
|
以下能力不承诺无损往返（可在 UI 上提示）：
|
|||
|
|
|
|||
|
|
- 复杂表格
|
|||
|
|
- 自定义 HTML 属性与内联样式
|
|||
|
|
- 任意嵌套块与第三方嵌入节点
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 安全策略
|
|||
|
|
|
|||
|
|
所有 HTML 渲染都应先经过 sanitize，再进入 `dangerouslySetInnerHTML`。
|
|||
|
|
|
|||
|
|
建议白名单：
|
|||
|
|
|
|||
|
|
- 标签：`p`, `br`, `strong`, `em`, `del`, `blockquote`, `ul`, `ol`, `li`, `code`, `pre`, `a`, `img`, `h1`, `h2`, `h3`
|
|||
|
|
- 属性：
|
|||
|
|
- `a`: `href`, `target`, `rel`
|
|||
|
|
- `img`: `src`, `alt`, `title`
|
|||
|
|
|
|||
|
|
安全要点：
|
|||
|
|
|
|||
|
|
- 禁止 `script`, `style`, `iframe` 等危险标签
|
|||
|
|
- 过滤事件属性（如 `onclick`）
|
|||
|
|
- 限制 `href/src` 协议（如仅 `http`, `https`, `data:image/*` 按需）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. 组件分层建议
|
|||
|
|
|
|||
|
|
保持以下分层，避免页面散落编辑逻辑：
|
|||
|
|
|
|||
|
|
- `UnifiedEditor`：模式分发、通用 props、统一事件
|
|||
|
|
- `HtmlEditor` / `MarkdownEditor`：各自实现细节
|
|||
|
|
- `EditorToolbar`：按 `features` 开关按钮
|
|||
|
|
- `convert.ts`：只做内容转换，不掺杂 UI
|
|||
|
|
- `viewer.tsx`：只读渲染，统一 sanitize + 样式
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. 分阶段实施计划
|
|||
|
|
|
|||
|
|
## Phase 1（低风险统一入口）
|
|||
|
|
|
|||
|
|
- 在 `web/components/editor` 补齐 `index.tsx`、`html.tsx`、`markdown.tsx` 的最小实现
|
|||
|
|
- 先迁移知识库文档编辑页到 `UnifiedEditor`
|
|||
|
|
- 保持 IM 场景暂不动，避免一次性改动过大
|
|||
|
|
|
|||
|
|
验收标准：
|
|||
|
|
|
|||
|
|
- 业务页不再直接判断 `Textarea` vs `RichTextEditor`
|
|||
|
|
- 保存结果与当前接口完全兼容
|
|||
|
|
|
|||
|
|
## Phase 2（收敛富文本能力）
|
|||
|
|
|
|||
|
|
- 抽象 TipTap schema/toolbar，沉淀为复用能力
|
|||
|
|
- 迁移 IM 编辑器到统一内核配置（保留其发送快捷键与图片上传行为）
|
|||
|
|
|
|||
|
|
验收标准：
|
|||
|
|
|
|||
|
|
- 共享核心扩展与样式策略
|
|||
|
|
- 场景差异通过 `features` 开关控制
|
|||
|
|
|
|||
|
|
## Phase 3（体验与可靠性增强）
|
|||
|
|
|
|||
|
|
- 引入草稿自动保存（localStorage 或服务端草稿）
|
|||
|
|
- 增加快捷键、字数统计、粘贴规则统一
|
|||
|
|
- 完善 sanitize 策略与回归测试
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. 测试建议
|
|||
|
|
|
|||
|
|
至少覆盖以下场景：
|
|||
|
|
|
|||
|
|
- markdown/html 各自编辑与保存
|
|||
|
|
- 模式切换提示与转换失败回退
|
|||
|
|
- 图片上传占位图替换成功/失败
|
|||
|
|
- HTML 渲染安全（XSS 用例）
|
|||
|
|
- 关键快捷键行为（Enter/Shift+Enter/Cmd+B）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 11. 风险与取舍
|
|||
|
|
|
|||
|
|
- 风险：追求“全格式无损转换”会导致实现复杂度急剧上升
|
|||
|
|
- 取舍：先定义“可稳定支持的语法子集”，其余场景用提示+降级策略处理
|
|||
|
|
- 收益：统一内核后，后续功能（草稿、插件、统计、主题）可一次开发多处复用
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 12. 与当前项目的直接对应
|
|||
|
|
|
|||
|
|
建议优先替换知识库文档编辑页中的分支逻辑（markdown 文本域 vs html 富文本），统一接入 `UnifiedEditor`。
|
|||
|
|
IM 编辑器可在下一阶段迁移到同一核心配置，避免破坏现有发送交互。
|
|||
|
|
|