5.8 KiB
前端写作体验优化开发说明
1. 本次目标
本次优化聚焦笔记写作主流程，不调整后端接口：
- 将界面中的装饰性 Emoji 统一替换为 Element Plus 图标；
- 将“写作”模式由 Markdown 源码与预览双栏改为单一可视化编辑区；
- 为写作区增加标题、加粗、斜体、有序列表、无序列表工具栏；
- 使用 Shiki 为 Markdown 代码块提供亮色、暗色双主题高亮。
2. 实现说明
2.1 图标体系
新增 AppIcon.vue 作为轻量图标出口，页面直接传入 @element-plus/icons-vue 组件。侧边栏、文件树、Vault 入口、主题按钮、空状态及扩展列表不再使用 Emoji 表达操作含义。
这样处理后，图标尺寸、颜色和主题状态都由 CSS 统一控制，也避免不同系统 Emoji 字体造成的显示差异。
2.2 可视化 Markdown 编辑器
写作模式使用 Milkdown Crepe 渲染 Markdown 文档，磁盘中仍保存标准 Markdown 文本。编辑器监听 Markdown 更新并写回 Pinia 状态，继续复用原有自动保存逻辑。
“源码”模式保留为独立模式，便于需要精确编辑 Markdown 的用户使用；写作模式中不再同时展示 Markdown 源码。
编辑器按当前文件路径重新挂载，保证切换文件、切换源码模式后，展示内容与 Store 中的最新 Markdown 一致。
2.3 Markdown 工具栏
写作区顶部提供以下基础格式操作：
- H1 至 H6 标题下拉选择，标题默认使用粗体显示；
- 加粗；
- 斜体；
- 有序列表；
- 无序列表；
- 12 px 至 32 px 字号选择；
- 行内代码与代码块；
- 行内公式与公式块；
- 链接插入。
标题、加粗、斜体和列表工具调用 Milkdown Command 修改当前选区或块级结构，因此能正确处理光标、选区和嵌套列表。工具栏使用常见的 H、B、I、1. 和 • 排版符号，减少图标语义歧义。
标准 Markdown 没有字号语法。字号功能仅在用户已选择文本时生效，并将内容写为兼容 Markdown 的内联 HTML：
<span style="font-size: 18px">选中的文本</span>
Milkdown 自定义插件在写作模式中隐藏 HTML 标记，并通过 ProseMirror Decoration 显示实际字号；切换到源码模式时可以直接看到并修改上述 Markdown 内容。
字号栏同时提供预设下拉框和 8–96 px 数值输入框。输入数值后按 Enter 或点击“应用”即可写入当前选区。标题下拉框提供“正文”选项，用于将标题恢复为普通段落；正文显式使用正常字重，只有 H1 至 H6 默认加粗。
选中文本后出现的 Crepe 浮动格式栏使用应用正文前景色、实色描边和悬浮强调色，避免亮暗主题下图标对比度不足。
浮动栏由 Crepe Tooltip Provider 挂载，不保证位于 Vue scoped 样式容器内部，因此对比度规则使用全局 .milkdown-toolbar 选择器，并通过主题变量适配亮暗模式。顶部格式按钮统一在 pointerdown 阶段阻止默认焦点迁移并执行命令，确保点击工具栏时不会丢失编辑器选区。
有序列表与无序列表使用相同尺寸、相同线条结构的经典列表符号，仅通过左侧的数字或圆点区分类型。亮色主题下，表格边框使用更高对比度的文本辅助色，列表序号、圆点及任务图标也改用辅助文本色并增加字重。
编辑器左侧加号打开的块菜单已完成中文本地化：
- “文本”分组包含正文、H1 至 H6、引用和分割线；
- “列表”分组包含无序列表、有序列表和任务列表；
- “插入”分组包含图片、代码块、表格和公式块。
代码语言搜索、复制操作、链接编辑及公式确认浮层也统一使用中文文案。
2.4 Shiki 高亮与主题适配
代码高亮使用 Shiki 的 JavaScript 正则引擎，并只注册第一阶段常用语言：Markdown、HTML、CSS、JavaScript、TypeScript、JSON、Python、Shell 和 SQL。未知语言回退为 Markdown 语法展示，不阻塞整篇内容渲染。
高亮结果同时生成 github-light 和 github-dark 颜色变量。根节点的 data-theme 变化后由 CSS 选择对应颜色，因此切换主题无需重新解析整篇 Markdown。
Shiki 应用于：
- 写作编辑器中的代码块高亮预览；
- AI 对话中的 Markdown 代码块。
Markdown HTML 仍在写入 DOM 前经过 DOMPurify 清理。
3. 新增依赖
@element-plus/icons-vue：统一界面图标；@milkdown/crepe、@milkdown/kit：可视化 Markdown 编辑器及命令；shiki、@shikijs/langs、@shikijs/themes、@shikijs/engine-javascript：代码高亮和按需语言注册。
4. 验证记录
在 frontend 目录执行：
pnpm build
pnpm test
验证结果：TypeScript 类型检查与 Vite 生产构建均通过。组件回归测试共 5 项，全部通过：
- 顶部工具栏对选区应用加粗；
- 浮动工具栏对选区应用斜体；
- 自定义字号输入写入 Markdown；
- 标题恢复为普通正文；
- 连续切换文件后渲染新文件内容。
文件切换失效的原因是旧实现先更新 currentFilePath、后等待文件内容，导致编辑器使用新路径和旧内容提前重建。现在改为文件读取成功后一次性提交路径和内容；读取失败时保留原文件及其内容。
本地内置浏览器测试运行时因环境资源路径缺失未能启动，因此本次没有把自动化交互测试列为已通过项。合并前建议人工检查一次工具栏选区操作、文件切换同步和亮暗主题下的代码块显示。
5. 后续建议
- 根据真实文档规模评估 Milkdown 与 Shiki 的懒加载拆包；
- 为工具栏补充撤销、重做、引用、行内代码和链接；
- 增加编辑器选区命令与文件切换的组件测试。