49 lines
3.8 KiB
Markdown
49 lines
3.8 KiB
Markdown
# Markdown 语法预设与外部文件刷新
|
||
|
||
日期：2026-09-06。
|
||
|
||
## 1. 设置入口与范围
|
||
|
||
“设置 → 编辑器 → Markdown 语法预设”管理语法与编辑行为，独立于“标题样式”的字号、字体和字重设置。
|
||
|
||
支持 ATX/Setext 标题、无序列表标记、有序列表递增、代码围栏、裸链接识别、数学公式、警告框、Mermaid、代码行号、自动换行、缩进和工具栏新建代码块的默认语言。Setext 只作用于 H1/H2。提供扩展、GitHub 和基础三组内置配置，支持最多 20 个命名自定义预设，同名保存替换旧配置。
|
||
|
||
配置保存在本机 localStorage 的 `markdown-preferences`，读取时校验。静态预览即时应用；写作编辑器在下次打开时应用，避免切换设置重建正在编辑的文档。写作模式保存会统一整篇正文的语法标记，源码模式保留手写语法。关闭扩展后对应内容按普通 Markdown/代码展示。
|
||
|
||
本次不是完整复制 Typora：未提供上下标、高亮、智能标点、physics 包及导出公式选项。基础配置仍支持现有 GFM 表格等功能。
|
||
|
||
## 2. 主题与折叠
|
||
|
||
六个主题共用语义颜色和表单控件。内置浅色、深色、护眼更新为 1.3.0；纸间时光 1.8.0；Ocean Blue 1.5.0；Midnight Purple 2.3.0。社区预览增加语法控件和标题折叠样本。
|
||
|
||
标题箭头使用统一 CSS 形状，默认隐藏，悬停标题或键盘聚焦按钮时显示；无悬停能力的触摸设备保持可见。用户自定义标题外观独立于主题配色。
|
||
|
||
## 3. 外部文件刷新与保存保护
|
||
|
||
Web 当前采用串行后台轮询：前一次完成后间隔两秒，在窗口聚焦时也检查。隐藏页面暂停读取，卸载移除监听。此机制不是原生文件事件监听；第三阶段可由 Tauri 文件事件替代。
|
||
|
||
`GET /workspace/tree` 检查磁盘新增、删除和重命名，为新文件登记元数据及全文索引，向量任务继续后台执行。前端保留文件夹展开状态，并丢弃过期请求响应。读取失败保留旧树并显示重试入口。
|
||
|
||
当前打开且未修改的文件检测到外部正文变化后更新编辑器；存在本地编辑时保留缓冲区，停止自动保存并提示冲突。重新加载磁盘版本需要用户确认。原文件删除或移动后，隐藏不可用的重新加载入口，提供下载当前 Markdown 副本和确认关闭笔记；取消关闭或确认期间正文改变时保留缓冲区。关闭后可重新选择其他文件，不再阻塞导航。`PATCH /notes/{note_id}` 新增可选 `expected_content_hash`（原始正文 UTF-8 SHA-256，64 位小写十六进制），保存前校验，不匹配返回 `NOTE_CONTENT_CONFLICT`，防止覆盖外部修改。
|
||
|
||
范围限制：现有文件的外部正文修改会刷新当前编辑器，但本轮目录检查不会据此重建其搜索索引；可通过重建索引同步检索内容。
|
||
|
||
## 4. 验证方法
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm run test
|
||
npm run build
|
||
cd ..
|
||
backend/.venv/Scripts/python.exe -m pytest backend/tests/test_workspace.py backend/tests/test_workspace_background.py -q -p no:cacheprovider
|
||
```
|
||
|
||
手工验证：
|
||
|
||
1. 保存并重新应用命名预设，刷新后确认保留；重新打开笔记，检查 Setext、列表和代码围栏的源码。
|
||
2. 切换六个主题，在社区预览和工作区检查控件、警告框、标题箭头；移出标题后箭头隐藏，Tab 聚焦仍可操作。
|
||
3. 在系统文件管理器新增、重命名、删除 Markdown 文件，保持前端可见，确认树自动更新且目录展开状态保留。
|
||
4. 分别在正文未修改、有未保存编辑时从外部修改同一文件，验证自动加载与冲突保护；拒绝重新加载应保留编辑内容。
|
||
|
||
本次自动验证覆盖预设持久化、解析选项隔离、写作语法输出、标题折叠、树刷新竞态、外部文件登记及保存冲突。
|