113 lines
5.8 KiB
Markdown
113 lines
5.8 KiB
Markdown
# 前端写作体验优化开发说明
|
||
|
||
## 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
|
||
<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` 目录执行：
|
||
|
||
```bash
|
||
pnpm build
|
||
pnpm test
|
||
```
|
||
|
||
验证结果：TypeScript 类型检查与 Vite 生产构建均通过。组件回归测试共 5 项，全部通过：
|
||
|
||
- 顶部工具栏对选区应用加粗；
|
||
- 浮动工具栏对选区应用斜体；
|
||
- 自定义字号输入写入 Markdown；
|
||
- 标题恢复为普通正文；
|
||
- 连续切换文件后渲染新文件内容。
|
||
|
||
文件切换失效的原因是旧实现先更新 `currentFilePath`、后等待文件内容，导致编辑器使用新路径和旧内容提前重建。现在改为文件读取成功后一次性提交路径和内容；读取失败时保留原文件及其内容。
|
||
|
||
本地内置浏览器测试运行时因环境资源路径缺失未能启动，因此本次没有把自动化交互测试列为已通过项。合并前建议人工检查一次工具栏选区操作、文件切换同步和亮暗主题下的代码块显示。
|
||
|
||
## 5. 后续建议
|
||
|
||
- 根据真实文档规模评估 Milkdown 与 Shiki 的懒加载拆包；
|
||
- 为工具栏补充撤销、重做、引用、行内代码和链接；
|
||
- 增加编辑器选区命令与文件切换的组件测试。
|