thzxx
4a1c06320f
- README.md: 更新版本号 v0.1.0，添加 CodeMirror 6 说明，添加关于/Gitee按钮说明 - DESIGN.md: 重写为当前架构，移除重构计划相关内容，精简为实际代码结构 - 删除 REFACTOR-PLAN.md（重构已完成）
351 lines
16 KiB
Markdown
351 lines
16 KiB
Markdown
# MarkLite v0.1.0 — 架构设计文档
|
||
|
||
## 1. 项目概述
|
||
|
||
MarkLite 是一款轻量级的 Windows 本地 Markdown 编辑器桌面应用程序。基于 Electron + React + TypeScript 构建，采用 CodeMirror 6 编辑器、Zustand 状态管理、IndexedDB 持久化、unified/rehype Markdown 渲染管线。
|
||
|
||
### 1.1 核心原则
|
||
|
||
1. **类型安全** — 全量 TypeScript，所有 IPC 通信、状态、接口均有类型定义
|
||
2. **模块化** — 源文件按职责分层：主进程 / 预加载 / 渲染进程（组件 / stores / hooks / lib / db / types）
|
||
3. **安全隔离** — contextIsolation + nodeIntegration:false + CSP + rehype-sanitize
|
||
4. **可测试性** — 业务逻辑（lib/）与 UI（components/）解耦
|
||
|
||
## 2. 技术架构
|
||
|
||
### 2.1 技术栈
|
||
|
||
| 组件 | 技术 | 版本 | 说明 |
|
||
|------|------|------|------|
|
||
| 桌面框架 | Electron | v28 | 跨平台桌面应用框架 |
|
||
| 前端框架 | React | v18 | 函数组件 + Hooks |
|
||
| 类型系统 | TypeScript | v5.6 | 全量类型安全 |
|
||
| 编辑器 | CodeMirror | v6 | 现代化代码编辑器 |
|
||
| 状态管理 | Zustand | v5 | 轻量级状态管理 |
|
||
| 持久化 | Dexie.js (IndexedDB) | v4 | 标签页状态 / 用户设置 / 最近文件 |
|
||
| Markdown 解析 | unified / remark / rehype | v11 | 插件化渲染管线 |
|
||
| 代码高亮 | rehype-highlight | v7 | 基于 highlight.js |
|
||
| 构建工具 | electron-vite | v3 | Electron + Vite，HMR 热更新 |
|
||
| 打包工具 | electron-builder | v25 | Windows NSIS 安装包 |
|
||
| 样式 | CSS Variables | — | 主题驱动，亮色/暗色 |
|
||
|
||
### 2.2 进程架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ Main Process (src/main/) 5 文件 │
|
||
│ index.ts 入口：窗口创建、app 生命周期、单实例锁 │
|
||
│ ipc-handlers.ts 所有 ipcMain.handle 注册 │
|
||
│ file-system.ts 文件读写、目录树构建、BOM 剥离 │
|
||
│ file-watcher.ts fs.watch 封装（单文件 + 目录监听） │
|
||
│ window-manager.ts 窗口创建、关闭拦截、单实例锁 │
|
||
└───────────────────────┬──────────────────────────────────────┘
|
||
│ contextBridge (安全隔离)
|
||
┌───────────────────────▼──────────────────────────────────────┐
|
||
│ Preload Script (src/preload/) 1 文件 │
|
||
│ index.ts contextBridge 类型安全暴露 │
|
||
│ electronAPI 22 个方法/事件的类型安全接口 │
|
||
└───────────────────────┬──────────────────────────────────────┘
|
||
│
|
||
┌───────────────────────▼──────────────────────────────────────┐
|
||
│ Renderer Process (src/renderer/) React 18 │
|
||
│ │
|
||
│ components/ (11) Toolbar · TabBar · Editor · Preview │
|
||
│ Sidebar · StatusBar · WelcomeScreen │
|
||
│ Toast · ModifiedBanner · DropOverlay │
|
||
│ │
|
||
│ stores/ (3) tabStore · editorStore · sidebarStore │
|
||
│ hooks/ (6) useTheme · useSettings · useKeyboard │
|
||
│ useDragDrop · useFileWatch · useUnsaved │
|
||
│ lib/ (3) markdown · fileUtils · constants │
|
||
│ db/ (4) schema · tab · settings · recentFiles │
|
||
│ types/ (6) tab · file · settings · ipc · index │
|
||
│ styles/ (3) variables · global · markdown-body │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ Shared (src/shared/) 2 文件 │
|
||
│ ipc-channels.ts IPC 通道名常量 │
|
||
│ types.ts 共享类型定义 │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.3 安全模型
|
||
|
||
| 层级 | 措施 | 说明 |
|
||
|------|------|------|
|
||
| Electron | `contextIsolation: true` | 渲染进程与主进程隔离 |
|
||
| Electron | `nodeIntegration: false` | 渲染进程无法访问 Node.js API |
|
||
| IPC | `contextBridge.exposeInMainWorld` | 仅暴露 22 个类型安全方法/事件 |
|
||
| CSP | `default-src 'self'; script-src 'self'` | 阻断内联脚本、外部资源 |
|
||
| HTML | `rehype-sanitize` | 渲染 Markdown 时过滤危险标签/属性 |
|
||
| 链接 | 协议白名单 | 仅允许 `http:` / `https:` / `#` 锚点 |
|
||
| 路径 | `validatePath()` | 防止路径遍历攻击 |
|
||
|
||
## 3. 状态管理架构
|
||
|
||
### 3.1 Zustand Stores
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ App.tsx (根组件) │
|
||
├─────────┬──────────┬──────────┬──────────┬──────────────┤
|
||
│Toolbar │ TabBar │ Sidebar │ Editor │ Preview │
|
||
│ │ │ │ (CM6) │ │
|
||
├─────────┴──────────┴──────────┴──────────┴──────────────┤
|
||
│ Zustand Stores │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ tabStore │ │editorStore│ │sidebarStore│ │
|
||
│ │ - tabs │ │- viewMode│ │- tree │ │
|
||
│ │- activeId│ │- darkMode│ │- expanded │ │
|
||
│ │ - mru │ │ │ │- rootPath │ │
|
||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
||
│ │ │ │ │
|
||
│ ┌────▼────────────▼────────────▼────────────────────┐ │
|
||
│ │ IndexedDB (Dexie.js) │ │
|
||
│ │ tabSnapshots │ settings │ recentFiles │ activeTab │ │
|
||
│ └───────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 tabStore — 标签页状态
|
||
|
||
```typescript
|
||
interface TabState {
|
||
tabs: Tab[] // 所有标签页
|
||
activeTabId: string | null // 当前活动标签 ID
|
||
mruStack: string[] // MRU 标签栈（Ctrl+Tab 切换）
|
||
|
||
createTab(filePath?, content?) // 创建标签（同文件不重复打开）
|
||
closeTab(tabId) // 关闭标签（自动切换到相邻标签）
|
||
switchToTab(tabId) // 切换标签
|
||
updateTabContent(tabId, content) // 更新内容（标记修改）
|
||
setModified(tabId, modified) // 设置修改状态
|
||
getActiveTab() // 获取当前标签
|
||
updateTabScroll(tabId, scroll) // 更新滚动/光标位置
|
||
saveToDB() // 保存到 IndexedDB
|
||
loadFromDB() // 从 IndexedDB 加载
|
||
}
|
||
```
|
||
|
||
### 3.3 editorStore — 编辑器状态
|
||
|
||
```typescript
|
||
interface EditorState {
|
||
viewMode: 'editor' | 'preview' // 视图模式
|
||
darkMode: boolean // 暗色主题
|
||
}
|
||
```
|
||
|
||
### 3.4 sidebarStore — 侧边栏状态
|
||
|
||
```typescript
|
||
interface SidebarState {
|
||
isVisible: boolean // 是否显示
|
||
rootPath: string | null // 当前打开的文件夹路径
|
||
tree: FileNode[] // 目录树数据
|
||
expandedDirs: Set<string> // 已展开的目录集合
|
||
sidebarWidth: number // 侧边栏宽度 (180~500)
|
||
}
|
||
```
|
||
|
||
## 4. 数据持久化 — IndexedDB
|
||
|
||
通过 Dexie.js 封装 IndexedDB：
|
||
|
||
### 4.1 数据库 Schema
|
||
|
||
```typescript
|
||
const db = new Dexie('MarkLite')
|
||
|
||
db.version(1).stores({
|
||
tabSnapshots: 'id, filePath, updatedAt', // 标签页快照
|
||
settings: 'id', // 用户设置
|
||
recentFiles: '++id, filePath, lastOpened', // 最近打开文件
|
||
activeTab: 'id' // 当前活动标签
|
||
})
|
||
```
|
||
|
||
### 4.2 数据模型
|
||
|
||
| Store | 字段 | 说明 |
|
||
|-------|------|------|
|
||
| `tabSnapshots` | id, filePath, content, scrollTop, selectionStart, selectionEnd, isModified, updatedAt | 标签页状态快照 |
|
||
| `settings` | id, darkMode, viewMode, sidebarCollapsed, sidebarWidth | 用户偏好设置 |
|
||
| `recentFiles` | ++id, filePath, lastOpened | 最近打开文件列表 |
|
||
| `activeTab` | id, activeTabId | 当前活动标签 ID |
|
||
|
||
## 5. IPC 通信设计
|
||
|
||
### 5.1 渲染进程 → 主进程（invoke）
|
||
|
||
| 通道 | 参数 | 返回值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `dialog:openFile` | 无 | `OpenFileResponse` | 打开文件对话框 |
|
||
| `file:read` | `filePath` | `ReadFileResult` | 读取文件内容 |
|
||
| `file:save` | `{ filePath, content }` | `SaveFileResult` | 保存文件 |
|
||
| `file:saveAs` | `{ content }` | `SaveFileResult` | 另存为 |
|
||
| `file:getCurrentPath` | 无 | `string \| null` | 获取当前文件路径 |
|
||
| `file:stats` | `filePath` | `FileStatsResult` | 获取文件元信息 |
|
||
| `file:reload` | 无 | `ReloadFileResult` | 重新加载当前文件 |
|
||
| `tab:switched` | `filePath \| null` | `void` | 通知主进程切换活动文件 |
|
||
| `window:forceClose` | 无 | `void` | 强制关闭窗口 |
|
||
| `window:cancelClose` | 无 | `void` | 取消关闭 |
|
||
| `dir:readTree` | `dirPath` | `ReadDirTreeResult` | 递归读取目录树 |
|
||
| `dir:openDialog` | 无 | `string \| null` | 打开文件夹选择对话框 |
|
||
| `dir:watch` | `dirPath` | `void` | 监听目录变化 |
|
||
| `dir:unwatch` | 无 | `void` | 停止监听目录变化 |
|
||
|
||
### 5.2 主进程 → 渲染进程（send）
|
||
|
||
| 通道 | 数据 | 说明 |
|
||
|------|------|------|
|
||
| `file:openInTab` | `{ filePath, content }` | 在新标签中打开文件 |
|
||
| `file:externallyModified` | `filePath` | 文件被外部修改 |
|
||
| `window:confirmClose` | 无 | 请求确认关闭 |
|
||
| `sidebar:dirChanged` | 无 | 目录结构变化 |
|
||
|
||
## 6. 编辑器架构 — CodeMirror 6
|
||
|
||
### 6.1 功能特性
|
||
|
||
- Markdown 语法高亮
|
||
- 行号显示
|
||
- 代码折叠 (foldGutter)
|
||
- 括号匹配 (bracketMatching)
|
||
- 搜索替换 (search) — 中文本地化
|
||
- 历史记录 (history) — 支持 undo/redo
|
||
- Tab 缩进 (indentWithTab)
|
||
- 自动换行 (lineWrapping)
|
||
- 暗色主题 (oneDark)
|
||
|
||
### 6.2 滚动与选区持久化
|
||
|
||
切换标签时自动保存/恢复：
|
||
- 滚动位置 (`scrollTop`)
|
||
- 光标选区 (`selectionStart`, `selectionEnd`)
|
||
|
||
## 7. Markdown 渲染管线
|
||
|
||
```
|
||
Markdown 文本
|
||
│
|
||
▼
|
||
remark-parse 解析为 MDAST
|
||
│
|
||
▼
|
||
remark-gfm 扩展 GFM 语法
|
||
│
|
||
▼
|
||
remark-rehype 转换为 HAST
|
||
│
|
||
▼
|
||
rehype-raw 解析内联 HTML
|
||
│
|
||
▼
|
||
rehype-sanitize 安全过滤
|
||
│
|
||
▼
|
||
rehype-fixImages 相对路径图片转 file:// URL
|
||
│
|
||
▼
|
||
rehype-highlight 代码语法高亮
|
||
│
|
||
▼
|
||
rehype-stringify 序列化为 HTML
|
||
│
|
||
▼
|
||
dangerouslySetInnerHTML 渲染到 DOM
|
||
```
|
||
|
||
## 8. UI 设计
|
||
|
||
### 8.1 色彩方案
|
||
|
||
#### 亮色主题
|
||
|
||
| 角色 | CSS 变量 | 色值 |
|
||
|------|----------|------|
|
||
| 主色调 | `--primary` | `#1a73e8` |
|
||
| 背景色 | `--bg` | `#ffffff` |
|
||
| 次级背景 | `--bg-secondary` | `#f8f9fa` |
|
||
| 文字色 | `--text` | `#333333` |
|
||
| 边框色 | `--border` | `#e1e4e8` |
|
||
|
||
#### 暗色主题
|
||
|
||
| 角色 | CSS 变量 | 色值 |
|
||
|------|----------|------|
|
||
| 主色调 | `--primary` | `#8ab4f8` |
|
||
| 背景色 | `--bg` | `#1e1e1e` |
|
||
| 次级背景 | `--bg-secondary` | `#252526` |
|
||
| 文字色 | `--text` | `#d4d4d4` |
|
||
| 边框色 | `--border` | `#3e3e3e` |
|
||
|
||
### 8.2 布局
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────────┐
|
||
│ MarkLite - filename.md ─ □ ✕ │
|
||
├──────────────────────────────────────────────────────────────────────────┤
|
||
│ 📁 打开 │ 💾 保存 │ ✏️ 编辑 │ 👁 预览 │ 🌙 🔗 ℹ️ │
|
||
├──────────────────────────────────────────────────────────────────────────┤
|
||
│ [file1.md] [file2.md] [未命名] [+] │
|
||
├──────────┬─────────────────────────────────────────────────────────────┤
|
||
│ 资源管理器 │ │
|
||
│ ▼ project │ 1 # Title │ Title │
|
||
│ 📁 src │ 2 │ ─────── │
|
||
│ 📄 file1│ 3 content... │ content... │
|
||
│ 📄 file2│ │ │
|
||
├──────────┴─────────────────────────────────────────────────────────────┤
|
||
│ filename.md │ UTF-8 │ Markdown │
|
||
└────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 9. 构建与发布
|
||
|
||
### 9.1 开发模式
|
||
|
||
```bash
|
||
npm run dev # electron-vite dev（HMR 热更新）
|
||
```
|
||
|
||
### 9.2 生产构建
|
||
|
||
```bash
|
||
npm run build # electron-vite build + electron-builder --win
|
||
npm run build:portable # 便携版（免安装）
|
||
```
|
||
|
||
### 9.3 打包配置
|
||
|
||
- 输出格式：NSIS 安装包（.exe）
|
||
- 目标平台：Windows x64
|
||
- 应用图标：assets/icon.ico
|
||
- 文件关联：`.md` / `.markdown` / `.txt`
|
||
- 支持自定义安装目录、桌面/开始菜单快捷方式
|
||
|
||
## 10. 依赖清单
|
||
|
||
### 运行时依赖
|
||
|
||
| 包名 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| react / react-dom | ^18.3 | UI 框架 |
|
||
| zustand | ^5.0 | 状态管理 |
|
||
| dexie | ^4.0 | IndexedDB 封装 |
|
||
| nanoid | ^5.0 | 唯一 ID 生成 |
|
||
| @codemirror/* | ^6.x | 代码编辑器 |
|
||
| unified / remark / rehype | ^11.0 | Markdown 渲染管线 |
|
||
| rehype-highlight | ^7.0 | 代码语法高亮 |
|
||
|
||
### 开发依赖
|
||
|
||
| 包名 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| electron | ^28.0 | 桌面框架 |
|
||
| electron-builder | ^25.0 | 打包工具 |
|
||
| electron-vite | ^3.0 | 构建工具 |
|
||
| typescript | ^5.6 | 类型系统 |
|
||
| eslint | ^9.0 | 代码检查 |
|