87 lines
4.0 KiB
Markdown
87 lines
4.0 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 内容。
|
||
|
||
选中文本后出现的 Crepe 浮动格式栏使用应用正文前景色、实色描边和悬浮强调色，避免亮暗主题下图标对比度不足。
|
||
|
||
### 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 的懒加载拆包；
|
||
- 为工具栏补充撤销、重做、引用、行内代码和链接；
|
||
- 增加编辑器选区命令与文件切换的组件测试。
|