3.2 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 工具栏
写作区顶部提供以下基础格式操作：
- 二级标题；
- 加粗；
- 斜体；
- 有序列表；
- 无序列表。
工具栏调用 Milkdown Command 修改当前选区或块级结构，不通过字符串拼接修改 Markdown，因此能正确处理光标、选区和嵌套列表。
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
验证结果：TypeScript 类型检查与 Vite 生产构建均通过。开发服务器根页面返回 HTTP 200。
本地内置浏览器测试运行时因环境资源路径缺失未能启动，因此本次没有把自动化交互测试列为已通过项。合并前建议人工检查一次工具栏选区操作、文件切换同步和亮暗主题下的代码块显示。
5. 后续建议
- 根据真实文档规模评估 Milkdown 与 Shiki 的懒加载拆包；
- 为工具栏补充撤销、重做、引用、行内代码和链接；
- 增加编辑器选区命令与文件切换的组件测试。