# 前端写作体验优化开发说明 ## 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： ```markdown 选中的文本 ``` Milkdown 自定义插件在写作模式中隐藏 HTML 标记，并通过 ProseMirror Decoration 显示实际字号；切换到源码模式时可以直接看到并修改上述 Markdown 内容。 选中文本后出现的 Crepe 浮动格式栏使用应用正文前景色、实色描边和悬浮强调色，避免亮暗主题下图标对比度不足。 有序列表与无序列表使用相同尺寸、相同线条结构的经典列表符号，仅通过左侧的数字或圆点区分类型。亮色主题下，表格边框使用更高对比度的文本辅助色，列表序号、圆点及任务图标也改用辅助文本色并增加字重。 编辑器左侧加号打开的块菜单已完成中文本地化： - “文本”分组包含正文、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` 目录执行： ```bash pnpm build ``` 验证结果：TypeScript 类型检查与 Vite 生产构建均通过。开发服务器根页面返回 HTTP 200。 本地内置浏览器测试运行时因环境资源路径缺失未能启动，因此本次没有把自动化交互测试列为已通过项。合并前建议人工检查一次工具栏选区操作、文件切换同步和亮暗主题下的代码块显示。 ## 5. 后续建议 - 根据真实文档规模评估 Milkdown 与 Shiki 的懒加载拆包； - 为工具栏补充撤销、重做、引用、行内代码和链接； - 增加编辑器选区命令与文件切换的组件测试。