NotesAgentic/docs/前端写作体验优化开发说明.md

前端写作体验优化开发说明

更新日期：2026-08-30。本文所述优化均已进入当前分支；前端完整回归基线为 14 项测试通过，TypeScript 检查和 Vite 生产构建通过。

1. 本次目标

本次优化聚焦笔记写作主流程，不调整后端接口：

• 将界面中的装饰性 Emoji 统一替换为 Element Plus 图标；
• 将“写作”模式由 Markdown 源码与预览双栏改为单一可视化编辑区；
• 为写作区增加标题、加粗、斜体、有序列表、无序列表工具栏；
• 写作页代码块默认展开为可编辑状态；只读 Markdown 区域使用 Shiki 提供亮暗主题高亮。

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 语法展示，不阻塞整篇内容渲染。

Shiki 同时生成 github-light 与 github-dark 两套 CSS 变量。主题页提供“跟随主题 / GitHub Light / GitHub Dark”选项，通过根节点 data-code-theme 切换对应变量，无需重新执行高亮。偏好写入 editor-appearance，内置主题和后续主题包也可通过 ThemeConfig.code_theme 指定默认代码主题。

代码块容器使用 GitHub 风格的背景、边框、6px 圆角、16px 内边距和等宽字体；相关颜色由 --color-code-* Token 控制，方便主题商店覆盖。

高亮结果同时生成 github-light 和 github-dark 颜色变量。根节点的 data-theme 变化后由 CSS 选择对应颜色，因此切换主题无需重新解析整篇 Markdown。

写作编辑器中的普通代码块进入文档后直接展开 CodeMirror 编辑区，不再先显示 Shiki 预览，也不再提供“编辑代码/查看高亮”切换，减少一次多余操作。公式块仍由 Milkdown 的 LaTeX 功能负责编辑和渲染。

Shiki 仅应用于：

• AI 对话中的 Markdown 代码块。
• Search、智能体等复用 MarkdownContent 的只读 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 生产构建均通过。当前前端完整回归测试共 14 项；其中写作与文件切换相关回归覆盖：

• 顶部工具栏对选区应用加粗；
• 浮动工具栏对选区应用斜体；
• 自定义字号输入写入 Markdown；
• 标题恢复为普通正文；
• 连续切换文件后渲染新文件内容；
• 从文件树连续点击时，活动路径与编辑器内容同步切换；
• 欢迎笔记的异步初始化不会覆盖用户刚点击的文件。

文件切换失效包含两层原因。第一层是旧实现先更新 currentFilePath、后等待文件内容，导致编辑器使用新路径和旧内容提前重建；现在改为文件读取成功后一次性提交路径和内容。第二层是工作区欢迎笔记的异步初始化结束后会无条件设为活动文件，可能覆盖用户在此期间的真实点击；现在点击文件时立即同步工作区活动路径，默认初始化仅在用户尚未选择文件且欢迎笔记确实加载成功时提交。文件读取失败时则恢复点击前的活动文件。

本地内置浏览器测试运行时因环境资源路径缺失未能启动，因此本次没有把自动化交互测试列为已通过项。合并前建议人工检查一次工具栏选区操作、文件切换同步，以及跟随主题、GitHub Light、GitHub Dark 三种代码块设置下的显示效果。

5. 后续建议

• 根据真实文档规模评估 Milkdown 与只读 Markdown 高亮模块的懒加载拆包；
• 为工具栏补充撤销、重做、引用、行内代码和链接；
• 增加编辑器选区命令与文件切换的组件测试。