8.6 KiB
8.6 KiB
1. 架构设计
graph TD
A[uTools Plugin Container] --> B[Vue 3 Frontend]
B --> C[preload/services.js]
C --> D[Node.js APIs]
C --> E[File System]
C --> F[Git Commands]
subgraph "Frontend Layer"
B --> G[Ant Design Vue Components]
B --> H[Markdown Editor]
B --> I[File Tree Component]
B --> J[Search Component]
end
subgraph "Node.js Service Layer"
C --> K[File Operations]
C --> L[Process Management]
C --> M[Git Integration]
C --> N[Data Persistence]
end
subgraph "System Layer"
D --> O[fs Module]
D --> P[path Module]
F --> Q[git CLI]
end
2. 技术描述
-
前端框架: Vue 3.5.13 + Composition API
-
UI 组件库: Ant Design Vue 4.2.6
-
构建工具: Vite 6.0.11
-
初始化工具: vite-init
-
插件平台: uTools
-
Markdown 渲染: markdown-it 14.1.0
-
JSON 编辑器: jsoneditor 10.4.2
-
进程管理: tree-kill 1.2.2
-
图标库: @ant-design/icons-vue 7.0.1
-
后端: Node.js (集成在 uTools preload 中)
3. 路由定义
由于这是 uTools 插件应用，采用单页面应用模式，通过组件状态管理不同功能展示：
| 路由/状态 | 用途 |
|---|---|
| /editor | 主编辑界面，包含文件树和编辑器 |
| /search | 搜索界面，支持内容和文件搜索 |
| /export | 导出界面，支持 HTML/PDF 导出 |
| /git | Git 操作界面，显示 Git 状态和操作 |
4. 核心模块架构
4.1 文件系统模块 (preload/services.js)
// 文件操作 API
class FileService {
// 读取目录结构
async readDirectory(path)
// 读取文件内容
async readFile(filePath)
// 写入文件内容
async writeFile(filePath, content)
// 创建文件夹
async createDirectory(path)
// 删除文件/文件夹
async deleteItem(path)
// 重命名文件/文件夹
async renameItem(oldPath, newPath)
// 复制文件/文件夹
async copyItem(sourcePath, destPath)
}
4.2 图片处理模块
// 图片处理 API
class ImageService {
// 处理粘贴的图片
async handlePastedImage(imageData, mdFilePath)
// 生成图片文件名（时间戳）
generateImageName()
// 创建图片目录
createImageDirectory(mdFileName)
// 保存图片到本地
async saveImage(imageData, directory)
}
4.3 Git 集成模块
// Git 操作 API
class GitService {
// 检测 Git 仓库
isGitRepository(path)
// 获取 Git 状态
async getStatus(path)
// 执行 Git 提交
async commit(path, message)
// 执行 Git 推送
async push(path)
// 执行 Git 拉取
async pull(path)
}
4.4 搜索模块
// 搜索服务 API
class SearchService {
// 内容搜索
async searchContent(directory, keyword, useRegex)
// 文件名搜索
async searchFileName(directory, keyword)
// 正则表达式搜索
searchWithRegex(content, pattern)
}
5. 数据模型
5.1 文件树数据结构
interface FileNode {
id: string;
name: string;
path: string;
type: 'file' | 'directory';
children?: FileNode[];
expanded?: boolean;
selected?: boolean;
}
interface FileTreeState {
rootPath: string;
nodes: FileNode[];
selectedFile: string | null;
expandedKeys: string[];
}
5.2 编辑器状态管理
interface EditorState {
currentFile: string | null;
content: string;
originalContent: string;
mode: 'source' | 'preview' | 'split';
isDirty: boolean;
cursorPosition: { line: number; column: number };
}
5.3 标签页状态管理
interface TabState {
activeTab: string; // 当前激活的标签页ID
tabs: Tab[];
homeTab: HomeTabData;
}
interface Tab {
id: string;
type: 'home' | 'file';
title: string;
filePath?: string;
content?: string;
isDirty?: boolean;
}
interface HomeTabData {
recentFiles: RecentFile[];
pinnedFiles: PinnedFile[];
}
interface RecentFile {
filePath: string;
fileName: string;
lastOpened: number; // 时间戳
}
interface PinnedFile {
filePath: string;
fileName: string;
pinnedAt: number; // 时间戳
}
5.4 搜索状态管理
interface SearchState {
keyword: string;
searchType: 'content' | 'filename';
useRegex: boolean;
results: SearchResult[];
isSearching: boolean;
}
interface SearchResult {
filePath: string;
fileName: string;
lineNumber?: number;
content?: string;
matchPositions: Array<{ start: number; end: number }>;
}
6. 组件架构
6.1 主应用组件结构
App.vue
├── FileTree.vue // 文件树组件
├── TabContainer.vue // 标签页容器组件（新增）
│ ├── HomeTab.vue // 首页标签组件（新增）
│ ├── FileTab.vue // 文件标签组件（新增）
│ └── TabBar.vue // 标签栏组件（新增）
├── Editor.vue // 编辑器组件
├── Preview.vue // 预览组件
├── SearchPanel.vue // 搜索面板
├── GitPanel.vue // Git 操作面板
├── Toolbar.vue // 工具栏
└── StatusBar.vue // 状态栏
6.2 核心组件职责
| 组件名称 | 主要职责 |
|---|---|
| FileTree.vue | 显示文件树结构，处理文件选择、右键菜单，支持文件置顶功能 |
| TabContainer.vue | 管理多标签页状态，处理标签页切换、关闭、创建 |
| HomeTab.vue | 显示最近打开文件列表和置顶文件列表，支持快速打开 |
| FileTab.vue | 显示单个文件的编辑器和预览面板 |
| TabBar.vue | 显示标签页标题，支持标签页切换和关闭 |
| Editor.vue | Markdown 编辑，语法高亮，实时预览 |
| Preview.vue | Markdown 渲染，同步滚动 |
| SearchPanel.vue | 搜索输入、结果展示、跳转定位 |
| GitPanel.vue | Git 状态显示、操作按钮 |
| Toolbar.vue | 模式切换、导出、搜索等快捷操作 |
| StatusBar.vue | 显示当前文件、光标位置等状态信息 |
7. 状态管理架构
采用 Vue 3 Composition API 的响应式状态管理：
// 全局状态管理
const useAppStore = () => {
const fileTree = reactive(useFileTree());
const tabs = reactive(useTabs()); // 新增标签页状态管理
const editor = reactive(useEditor());
const search = reactive(useSearch());
const git = reactive(useGit());
const config = reactive(useConfig()); // 新增配置管理
return {
fileTree,
tabs,
editor,
search,
git,
config
};
};
// 配置管理模块
const useConfig = () => {
const configFileName = '.md-helper.json';
const loadConfig = async (rootPath) => {
// 从当前根目录加载配置文件
const configPath = path.join(rootPath, configFileName);
// 读取并解析配置文件
};
const saveConfig = async (rootPath, configData) => {
// 保存配置到当前根目录
const configPath = path.join(rootPath, configFileName);
// 写入配置文件
};
return {
loadConfig,
saveConfig,
configFileName
};
};
8. 性能优化策略
8.1 文件系统优化
-
使用异步文件操作，避免阻塞 UI
-
实现文件内容缓存，减少重复读取
-
大文件采用分块读取策略
8.2 搜索优化
-
使用 Web Worker 进行搜索计算
-
实现搜索结果的增量更新
-
添加搜索防抖机制
8.3 标签页性能优化
-
标签页内容懒加载，只有激活的标签页才渲染编辑器
-
最近打开文件列表限制数量（最多10个），避免列表过长
-
置顶文件配置使用 Set 数据结构，提高查找效率
-
标签页切换时保留编辑器状态，避免重复初始化
8.4 渲染优化
-
Markdown 渲染结果缓存
-
虚拟滚动处理长文档
-
图片懒加载机制
9. 错误处理机制
9.1 文件操作错误
-
权限错误提示
-
文件不存在处理
-
磁盘空间不足警告
9.2 Git 操作错误
-
网络错误处理
-
冲突解决提示
-
认证失败处理
9.3 用户输入错误
-
文件名非法字符检测
-
路径有效性验证
-
输入格式检查