You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
5.4 KiB
5.4 KiB
Markdown 编辑器统一为 Vditor 设计
1. 背景与目标
当前项目在可编辑 Markdown 输入场景使用 md-editor-v3。本次需求是将所有“可编辑输入”场景统一替换为 Vditor，并明确端侧体验策略：
- PC 端：完整工具栏 + 预览能力（A）
- 移动端：编辑优先、精简工具栏、预览为次级入口（B）
本次设计目标：
- 统一编辑器技术栈，降低后续维护成本。
- 保持现有数据契约与后端 API 不变，避免不必要联动改造。
- 保证移动端可用性，不牺牲主要输入效率。
- 将改动收敛在单一封装组件，减少页面级回归风险。
2. 方案结论
采用 方案 1：保留现有组件入口，内部替换为 Vditor。
- 对外继续使用
PostBodyMarkdownEditor与v-model。 - 组件内部从
md-editor-v3切换到Vditor实例化与事件同步。 - 页面侧（如新建/编辑文章）尽量零改动或仅最小改动。
不采用其余方案原因：
- 新建并行组件逐页替换：会增加过渡期双栈维护成本。
- 抽象多编辑器驱动层：对当前“统一到 Vditor”目标属于过度设计。
3. 范围与边界
3.1 本次范围
- 所有“可编辑 Markdown 输入”页面统一使用
Vditor封装。 - 包括但不限于文章新建、文章编辑等输入表单场景。
3.2 非本次范围
- 只读预览/渲染页面（例如公开页渲染链路）不改为 Vditor 渲染。
- 服务端 Markdown 处理、导出、清洗逻辑不因本次改造重写。
- 非 Markdown 输入控件不纳入改造。
4. 架构设计
4.1 组件边界
- 保留
PostBodyMarkdownEditor作为唯一编辑器入口组件。 - 组件输入：
modelValue: string - 组件输出：
update:modelValue（Markdown 文本） - 组件职责：
- 初始化/销毁 Vditor 实例
- 双向同步内容
- 端侧差异化配置（PC/移动端）
- 上传回调与错误提示
4.2 生命周期与运行环境
- 仅客户端初始化（保持
ClientOnly思路），避免 SSR 下访问window/document。 - 组件卸载时必须销毁实例，避免重复绑定与内存泄漏。
- 路由切换或父级重渲染后，可稳定恢复编辑内容。
4.3 数据契约
- 持续使用纯 Markdown 字符串作为唯一存储/传输格式。
- 不引入额外富文本 JSON 结构。
- 与现有保存 API 入参保持一致：
bodyMarkdown不变。
5. 交互与端侧策略
5.1 PC 端策略（A）
- 默认完整工具栏，覆盖高频与中频编辑操作。
- 保留预览能力，满足边写边看排版需求。
- 维持大编辑区高度，保障长文编辑连续性。
5.2 移动端策略（B）
- 默认“编辑优先”视图，输入区占据主区域。
- 工具栏精简为高频操作：
- 粗体、斜体、标题、列表、链接、图片、代码块
- 预览作为次级入口（切换按钮或分段视图），不默认占据主区域。
- 调整高度与滚动行为，降低软键盘弹起带来的遮挡风险。
5.3 内容同步规则
- 外部
modelValue变化时，编辑器内容同步更新。 - 编辑器内容变化时，实时触发
update:modelValue。 - 避免循环赋值：当内容未变化时不重复 setValue。
6. 上传与错误处理
- 图片上传继续复用现有
/api/file/upload接口与鉴权方式。 - 上传成功后插入返回 URL。
- 上传失败时通过 toast 提示，但不阻断用户继续编辑。
- 网络异常与接口异常统一走已有错误处理体验，不新增后端协议。
7. 兼容性与回归风险
7.1 需保持不变的能力
- Front matter 清理策略与渲染安全策略（如 HTML 禁用）保持现有语义。
- 文章保存、回填、预览链路的字段名与行为保持一致。
- 字数统计继续基于 Markdown 文本计算。
7.2 主要风险
- 编辑器实例销毁不完整导致重复监听。
- 移动端工具栏过多导致输入区被压缩。
- 外部值同步与内部变更监听冲突，造成内容抖动。
- 图片上传回调与编辑器插入语法对接不一致。
7.3 风险缓解
- 在组件层集中处理初始化、销毁、监听与去重逻辑。
- 以断点配置拆分 PC/移动端 toolbar，避免“一套配置走天下”。
- 对上传、保存、回填做最小闭环手测与自动化回归。
8. 验收标准
- 所有 Markdown 可编辑输入页面均使用统一 Vditor 封装组件。
- 新建与编辑文章场景可正常输入、保存、回填。
- 图片上传成功可插入，失败有可见提示。
- PC 端满足“完整工具栏 + 预览”；移动端满足“编辑优先 + 精简工具栏 + 次级预览”。
- 无 SSR 客户端对象报错；路由切换后无明显实例泄漏迹象。
- 服务端接口与数据结构无需改造即可兼容上线。
9. 实施边界（本阶段）
本文件仅定义设计与验收，不直接包含代码实现。
下一步进入实现计划阶段，将改造拆解为可执行任务（依赖调整、组件替换、页面回归、测试与发布验证）。
10. 规格自检（已完成）
- 已检查：无 TBD/TODO 等占位符。
- 已检查：范围仅覆盖“可编辑输入场景”，与用户约束一致。
- 已检查：PC 与移动端策略明确，未出现互相冲突描述。
- 已检查：验收标准可执行、可验证，且与架构边界一致。