619 lines
27 KiB
Markdown
619 lines
27 KiB
Markdown
# 模块开发指南
|
||
|
||
本文档详细说明 Thing 应用的模块系统架构，帮助开发者快速理解并创建新模块。
|
||
|
||
## 架构概述
|
||
|
||
Thing 采用**统一模块注册机制**，每个模块通过 `index.ts` 自描述其全部配置（名称、图标、组件、搜索项、进程配置、生命周期钩子等），由中央注册表 `moduleRegistry` 统一管理。
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ main.ts │
|
||
│ import './modules' (触发注册) │
|
||
└──────────────────────┬──────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ src/modules/index.ts │
|
||
│ 聚合入口：导入所有模块配置并注册 │
|
||
└──────────────────────┬──────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ src/modules/registry.ts │
|
||
│ ModuleRegistry 单例：注册 / 查询 / 组件懒加载 │
|
||
└──────┬───────────────┬───────────────┬──────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
App.vue Sidebar.vue GeneralSettings
|
||
(组件加载) (侧边栏导航) (模块开关管理)
|
||
```
|
||
|
||
## 核心文件说明
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `src/types/module.ts` | 模块配置类型定义 |
|
||
| `src/modules/registry.ts` | 注册表单例：注册、查询、组件懒加载缓存 |
|
||
| `src/modules/index.ts` | 聚合入口：导入并注册所有模块 |
|
||
| `src/modules/icons.ts` | 模块图标映射表 |
|
||
| `src/modules/<name>/index.ts` | 各模块的配置声明 |
|
||
| `src/modules/<name>/*.vue` | 模块前端组件 |
|
||
|
||
## 模块配置类型
|
||
|
||
```typescript
|
||
// src/types/module.ts
|
||
|
||
interface ModuleConfig {
|
||
/** 模块唯一标识（如 'proxy'、'clipboard'） */
|
||
id: string
|
||
/** 显示名称 */
|
||
name: string
|
||
/** 图标标识（对应 icons.ts 中的 key） */
|
||
icon: string
|
||
/** 模块描述（显示在设置界面的模块管理中） */
|
||
description: string
|
||
/** 模块分类 */
|
||
category: 'network' | 'tool' | 'system' | 'media'
|
||
/** 默认是否启用（默认 true） */
|
||
defaultEnabled?: boolean
|
||
/** 是否为内置模块（不可禁用，如设置模块） */
|
||
builtin?: boolean
|
||
/** 懒加载组件的 loader 函数（推荐） */
|
||
loader?: () => Promise<{ default: Component }>
|
||
/** 直接组件引用（内置模块可用，无需懒加载） */
|
||
component?: Component
|
||
/** 全局搜索项 */
|
||
searchItems?: SearchIndexItem[]
|
||
/** 进程配置（需要管理子进程的模块填写） */
|
||
process?: ModuleProcessConfig
|
||
/** 生命周期钩子 */
|
||
lifecycle?: ModuleLifecycle
|
||
/** 排序权重（数值越小越靠前，默认 100） */
|
||
order?: number
|
||
}
|
||
```
|
||
|
||
## 创建新模块
|
||
|
||
### 第 1 步：创建模块目录
|
||
|
||
```
|
||
src/modules/my-module/
|
||
├── index.ts # 模块配置
|
||
└── MyModule.vue # 前端组件
|
||
```
|
||
|
||
### 第 2 步：编写模块配置
|
||
|
||
```typescript
|
||
// src/modules/my-module/index.ts
|
||
import type { ModuleConfig } from '@/types/module'
|
||
|
||
export const moduleConfig: ModuleConfig = {
|
||
id: 'my-module',
|
||
name: '我的模块',
|
||
icon: 'my-module', // 需在 icons.ts 中添加映射
|
||
description: '模块功能描述',
|
||
category: 'tool',
|
||
defaultEnabled: true,
|
||
loader: () => import('./MyModule.vue'),
|
||
searchItems: [
|
||
{
|
||
title: '功能名称',
|
||
description: '功能描述',
|
||
keywords: ['关键词1', '关键词2', 'keyword']
|
||
}
|
||
],
|
||
order: 70
|
||
}
|
||
```
|
||
|
||
### 第 3 步：注册模块
|
||
|
||
在 `src/modules/index.ts` 中添加导入：
|
||
|
||
```typescript
|
||
import { moduleConfig as myModule } from './my-module'
|
||
|
||
const allModules: ModuleConfig[] = [
|
||
// ... 已有模块
|
||
myModule
|
||
]
|
||
|
||
moduleRegistry.registerAll(allModules)
|
||
```
|
||
|
||
### 第 4 步：添加图标映射
|
||
|
||
在 `src/modules/icons.ts` 中添加：
|
||
|
||
```typescript
|
||
import { Wrench } from '@lucide/vue' // 选择合适的图标
|
||
|
||
export const moduleIconMap: Record<string, Component> = {
|
||
// ... 已有映射
|
||
'my-module': Wrench
|
||
}
|
||
```
|
||
|
||
### 第 5 步（可选）：添加 Rust 后端命令
|
||
|
||
如果模块需要 Rust 后端支持，在 `src-tauri/src/` 中创建命令模块，并在 `lib.rs` 的 `invoke_handler` 中注册。
|
||
|
||
## 进程管理
|
||
|
||
需要管理外部子进程的模块（如 mihomo）通过 `ModuleProcessConfig` 声明进程配置。下载器模块使用进程内自建下载引擎，不涉及外部子进程管理。
|
||
|
||
### 配置示例
|
||
|
||
```typescript
|
||
// src/modules/proxy/index.ts
|
||
export const moduleConfig: ModuleConfig = {
|
||
// ...
|
||
process: {
|
||
name: 'mihomo', // 进程标识
|
||
executable: '', // 可执行文件路径（运行时确定）
|
||
args: ['-f', 'config.yaml'], // 启动参数
|
||
autoStart: false, // 模块启用时是否自动启动
|
||
restartOnCrash: true, // 崩溃后自动重启
|
||
maxRestarts: 3 // 最大重启次数（0 = 不限制）
|
||
}
|
||
}
|
||
```
|
||
|
||
### 前端 API
|
||
|
||
```typescript
|
||
import { useProcessStore } from '@/stores/processStore'
|
||
|
||
const processStore = useProcessStore()
|
||
|
||
// 通过模块 ID 启动进程（自动读取模块配置）
|
||
await processStore.startByModule('proxy')
|
||
|
||
// 停止进程
|
||
await processStore.stopByModule('proxy')
|
||
|
||
// 获取进程状态（从缓存读取）
|
||
const status = processStore.getProcessStatus('proxy')
|
||
// status.status: 'running' | 'stopped' | 'crashed' | 'starting'
|
||
|
||
// 刷新所有进程状态
|
||
await processStore.refreshAll()
|
||
```
|
||
|
||
### 自动化行为
|
||
|
||
模块启用/禁用时，`appStore.toggleModule` 会自动处理：
|
||
|
||
| 操作 | 禁用模块 | 启用模块 |
|
||
|------|----------|----------|
|
||
| 进程 | 停止运行中的进程 | 若 `autoStart` 为 true，启动进程 |
|
||
| 搜索项 | 移除该模块的搜索项 | 恢复该模块的搜索项 |
|
||
| 组件缓存 | 清除组件缓存，释放内存 | 下次访问时重新懒加载 |
|
||
| 生命周期 | 调用 `onDisable` 钩子 | 调用 `onEnable` 钩子 |
|
||
| 侧边栏 | 从侧边栏隐藏 | 在侧边栏显示 |
|
||
| Toast 通知 | 显示"已禁用 {模块名}" | 显示"已启用 {模块名}" |
|
||
|
||
## 生命周期钩子
|
||
|
||
```typescript
|
||
interface ModuleLifecycle {
|
||
/** 模块首次加载时调用 */
|
||
onInit?: () => void | Promise<void>
|
||
/** 模块组件挂载时调用（切换到该模块） */
|
||
onActivate?: () => void | Promise<void>
|
||
/** 模块组件卸载时调用（切换离开该模块） */
|
||
onDeactivate?: () => void | Promise<void>
|
||
/** 模块被禁用时调用 */
|
||
onDisable?: () => void | Promise<void>
|
||
/** 模块被启用时调用 */
|
||
onEnable?: () => void | Promise<void>
|
||
}
|
||
```
|
||
|
||
使用示例：
|
||
|
||
```typescript
|
||
export const moduleConfig: ModuleConfig = {
|
||
// ...
|
||
lifecycle: {
|
||
onEnable: async () => {
|
||
console.log('模块已启用')
|
||
// 初始化资源、建立连接等
|
||
},
|
||
onDisable: async () => {
|
||
console.log('模块已禁用')
|
||
// 释放资源、关闭连接等
|
||
},
|
||
onActivate: () => {
|
||
console.log('用户切换到本模块')
|
||
// 开始实时数据更新等
|
||
},
|
||
onDeactivate: () => {
|
||
console.log('用户离开本模块')
|
||
// 暂停实时更新以节省资源
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 全局搜索
|
||
|
||
模块通过 `searchItems` 声明可被全局搜索的功能项。用户在标题栏搜索框输入关键词时，匹配的搜索项会显示在结果列表中。
|
||
|
||
```typescript
|
||
searchItems: [
|
||
{
|
||
title: '代理设置', // 显示标题
|
||
description: '配置网络代理', // 显示描述
|
||
keywords: ['代理', 'proxy', '网络'] // 匹配关键词
|
||
}
|
||
]
|
||
```
|
||
|
||
如果搜索项需要执行特定操作（如跳转到子页面、触发命令），在模块组件挂载时通过 `searchStore.registerAction` 注册：
|
||
|
||
```typescript
|
||
import { useSearchStore } from '@/stores/searchStore'
|
||
|
||
const searchStore = useSearchStore()
|
||
|
||
onMounted(() => {
|
||
// 注册第 0 个搜索项的 action
|
||
searchStore.registerAction('my-module', 0, () => {
|
||
// 跳转到特定子页面或执行操作
|
||
activeTab.value = 'settings'
|
||
})
|
||
})
|
||
```
|
||
|
||
## 模块分类
|
||
|
||
| 分类 | 说明 | 适用场景 |
|
||
|------|------|----------|
|
||
| `network` | 网络相关 | 代理、下载器、网络工具 |
|
||
| `tool` | 实用工具 | 剪贴板、文件搜索、文本处理 |
|
||
| `system` | 系统相关 | 硬件监控、系统设置 |
|
||
| `media` | 媒体相关 | 截图、录屏、图片处理 |
|
||
|
||
分类目前用于元信息标记，未来可用于设置界面的分组展示。
|
||
|
||
## 模块禁用机制详解
|
||
|
||
当用户在设置页面切换模块开关时：
|
||
|
||
```
|
||
用户点击开关
|
||
│
|
||
▼
|
||
appStore.toggleModule(moduleId, enabled)
|
||
│
|
||
├─ 禁用时：
|
||
│ ├─ searchStore.unregisterModule(moduleId) // 移除搜索项
|
||
│ ├─ processStore.stopByModule(moduleId) // 停止进程
|
||
│ ├─ config.lifecycle?.onDisable?.() // 生命周期钩子
|
||
│ ├─ moduleRegistry.clearComponentCache(id) // 清除组件缓存
|
||
│ ├─ modules[id].enabled = false // 更新状态
|
||
│ └─ toast.success('已禁用 {模块名}') // 通知用户
|
||
│
|
||
└─ 启用时：
|
||
├─ modules[id].enabled = true // 更新状态
|
||
├─ config.lifecycle?.onEnable?.() // 生命周期钩子
|
||
├─ searchStore.registerItem(...) // 恢复搜索项
|
||
├─ processStore.startByModule(moduleId) // 启动进程（若 autoStart）
|
||
└─ toast.success('已启用 {模块名}') // 通知用户
|
||
```
|
||
|
||
禁用后的效果：
|
||
- 模块从侧边栏导航中隐藏
|
||
- 模块的搜索项从全局搜索中移除
|
||
- 模块的后台进程被停止
|
||
- 模块的组件缓存被清除，释放内存
|
||
- 如果当前正在查看被禁用的模块，自动切换到第一个可用模块
|
||
|
||
## 注意事项
|
||
|
||
1. **模块 ID 必须唯一**：重复注册会被忽略并输出警告
|
||
2. **图标必须映射**：模块配置中的 `icon` 字符串必须在 `icons.ts` 中有对应映射，否则回退到 Settings 图标
|
||
3. **懒加载优先**：使用 `loader` 而非 `component`，避免首屏加载所有模块代码
|
||
4. **避免循环依赖**：模块的 `index.ts` 只导出配置，不导入其他模块的 store
|
||
5. **进程配置的 executable**：通常留空，由模块组件在运行时根据用户设置确定实际路径
|
||
6. **内置模块**：设置 `builtin: true` 的模块不可被用户禁用，开关处于禁用状态
|
||
|
||
## 跨模块开发经验（代理模块沉淀）
|
||
|
||
以下要点来自代理模块开发，对后续涉及子进程管理、外部 API 交互、shadcn-vue 组件使用的模块同样适用。
|
||
|
||
### Tauri 命令与主线程
|
||
|
||
- **同步命令（`pub fn`）会阻塞主线程**：Tauri 的同步命令在主线程执行，其内部的 `std::thread::sleep`、磁盘 I/O、网络请求会阻塞所有 async 命令的调度。涉及等待/阻塞操作的命令必须声明为 `pub async fn`，并用 `tauri::async_runtime::spawn_blocking(|| { std::thread::sleep(...) }).await` 将阻塞操作放到线程池。
|
||
- **Windows 端口释放有延迟**：`child.kill()` + `child.wait()` 后 TCP 端口不会立即可用，需等待约 800ms 再重新绑定。重启类命令应预留此延迟。
|
||
- **`Mutex` 持锁期间禁止 sleep**：`ProcessManager::check_and_cleanup` 等持锁函数中不要执行长时间 sleep，否则会阻塞所有需要该锁的命令（如状态查询）。应先释放锁再 sleep，或移出临界区。
|
||
- **进程监控线程**：`start_monitoring_thread` 每 3 秒检查一次进程状态，崩溃时自动重启（可配置 `maxRestarts`）。前端通过监听 `process-status-changed` 事件更新 UI。
|
||
|
||
### 外部 API 交互
|
||
|
||
- **API 就绪轮询**：子进程 spawn 后 API 不会立即可用（需初始化配置、加载 geo 文件等）。前端应在请求前轮询健康检查接口（如 `/version`），500ms 间隔、10s 超时。
|
||
- **缓存配置避免频繁读盘**：后端 Manager 每次方法调用都从磁盘读 settings 会拖慢批量操作。建议在 Manager 内维护内存缓存，`save_settings` 时同步更新。
|
||
- **并发请求限流**：批量测速等场景不要一次性 `Promise.all` 全部请求，应分批（如每批 20 个），避免压垮子进程。
|
||
|
||
### shadcn-vue / reka-ui 注意事项
|
||
|
||
- **Select 禁止空字符串 value**：`<SelectItem value="">` 会触发警告并失效。使用哨兵值（如 `__default__`、`__all__`）替代空字符串，在 `@update:model-value` 回调中转回空值。
|
||
- **Select 双击问题**：reka-ui Select 的 DismissableLayer + closeAutoFocus 会导致连续点击两个 Select 时第一次点击仅关闭上一个、需第二次点击才打开下一个。当前未完美解决，建议同一界面避免放置过多相邻 Select。
|
||
- **Switch 使用 `model-value` / `update:model-value`**：reka-ui v2+ 的 Switch 不再使用 `checked` / `update:checked`。
|
||
- **Sonner toast 不可见**：通常是缺少 `vue-sonner/lib/index.css` 导入，而非 z-index 问题。确保在入口处导入该 CSS。
|
||
- **AlertDialog 替代 confirm()**：原生 `confirm()` 在 Tauri WebView 中样式不一致，使用 shadcn-vue AlertDialog 封装 Promise 化的 `showConfirm()` 函数，支持 destructive 样式。
|
||
|
||
### 数据一致性与自愈
|
||
|
||
- **配置文件与磁盘 reconcile**：settings.json 中的列表（如订阅 profiles）可能与磁盘文件不同步（用户手动删除、反序列化失败被 default 覆盖）。每次 `load_settings` 时应扫描磁盘补全缺失条目，并在 `currentProfile` 为 null 时自动指向第一个。
|
||
- **操作顺序防重复**：导入文件后写入 settings 时，若先写文件再 load_settings（含 reconcile 扫盘），reconcile 会扫到新文件添加一次，随后 push 又添加一次。应先 load_settings → 写文件 → push（加去重保护）。
|
||
- **子进程崩溃循环防护**：子进程因依赖文件损坏（如 geo 数据库）崩溃时，`restart_on_crash` 会反复重启。需配置备用下载源（如 jsdelivr 镜像）避免无代理时 GitHub 超时。
|
||
|
||
### UI 细节
|
||
|
||
- **瀑布流布局避免卡片等高撑开**：使用 `columns-1 md:columns-2 gap-4 [&>*]:mb-4 [&>*]:break-inside-avoid` 替代 `grid`，让卡片按内容高度自然排列。
|
||
- **模块禁用清理系统状态**：模块 `onDisable` 钩子应清理系统级副作用（如系统代理注册表项），避免模块停用后遗留导致系统异常。
|
||
- **应用退出清理**：在 `lib.rs` 的 `quit_app` 命令和托盘退出事件中都要调用 `cleanup_on_exit` + `stop_all`，确保任何退出路径都清理干净。
|
||
|
||
## 近期重要变更（影响其他模块开发）
|
||
|
||
以下是最近几次改动中确立的约定和模式，开发新模块时需遵循。
|
||
|
||
### 后端：子进程启动必须隐藏控制台窗口
|
||
|
||
`process_manager.rs` 暴露了公共函数 `setup_creation_flags(cmd: &mut Command)`，Windows 上会设置 `CREATE_NO_WINDOW` 标志。
|
||
|
||
**所有用 `std::process::Command` 启动外部程序的地方都必须调用它**，否则会弹出黑色控制台窗口（即使程序是后台运行）。包括：
|
||
|
||
- `ProcessManager::start()` 启动 mihomo 等内核
|
||
- `ProcessManager::check_and_cleanup()` 崩溃重启
|
||
- 任何调用 `mihomo.exe -v` 等查询版本的场景
|
||
|
||
跨平台：非 Windows 平台该函数为空实现，无需条件编译。
|
||
|
||
```rust
|
||
use crate::process_manager::setup_creation_flags;
|
||
|
||
let mut cmd = std::process::Command::new(&path);
|
||
cmd.arg("-v");
|
||
setup_creation_flags(&mut cmd); // 必须调用
|
||
cmd.stdout(Stdio::piped()).stderr(Stdio::null()).stdin(Stdio::null());
|
||
```
|
||
|
||
### 后端：长时间 wait() 不要阻塞主线程
|
||
|
||
`ProcessManager::stop()` 中 `child.kill()` 是快速的，但 `child.wait()` 可能阻塞几十到几百毫秒。**wait() 已移到后台线程**：
|
||
|
||
```rust
|
||
thread::spawn(move || {
|
||
let _ = entry.child.wait();
|
||
});
|
||
```
|
||
|
||
新模块若有类似的"终止外部进程"逻辑，也应遵循此模式，避免 Tauri 命令阻塞导致前端卡顿。
|
||
|
||
### 后端：内核/二进制下载用流式 + 事件推送
|
||
|
||
`mihomo_manager/` 目录（`kernel.rs`）的 `install_kernel` 确立了"下载二进制资源"的标准模式，未来若有其他模块需要下载外部内核时应复用：
|
||
|
||
- **流式下载**：`reqwest::Response::bytes_stream()` + `futures_util::StreamExt`，避免大文件一次性读入内存
|
||
- **进度事件**：通过 `app.emit("xxx-install-progress", progress)` 推送，事件载荷结构参考 `InstallProgress`
|
||
- **事件节流**：仅在百分比变化 ≥1% 时 emit，避免事件轰炸
|
||
- **zip 解压**：用 `zip` crate（纯 Rust），不要用 PowerShell `Expand-Archive`（有执行策略问题）
|
||
- **文件名匹配**：解压后用 `find_exe_in_dir` 查找 `.exe`（zip 内文件名可能含版本号，不是固定名字），找到后重命名为标准名
|
||
|
||
### 后端：GitHub API rate limit 规避
|
||
|
||
`check_kernel_update` 采用 **API 优先 + 重定向回退** 策略：
|
||
|
||
1. 先调 `api.github.com/.../releases/latest`（能拿完整资产列表，命名变化时更健壮）
|
||
2. 失败（403 rate limit / 网络错误）时回退到访问 `github.com/.../releases/latest`，从 302 重定向的最终 URL 提取版本号，按稳定命名规则构造下载 URL
|
||
|
||
**新模块若需要查 GitHub 最新版本，应复用此模式**，不要直接调 API（未认证 60次/小时/IP 极易超限）。
|
||
|
||
### 后端：资产命名规则适配
|
||
|
||
mihomo v1.19+ 改了 Windows 资产命名，按 CPU 微架构分级：
|
||
|
||
- 旧：`mihomo-windows-amd64-vX.X.X.zip`（已废弃）
|
||
- 新：`mihomo-windows-amd64-v3-vX.X.X.zip`（v1/v2/v3 对应 CPU level）
|
||
|
||
`fetch_latest_via_api` 中的匹配优先级：v3 标准 > v3-go124 > v3-go123 > v3 其他 > v2 > v1 > 旧命名。若未来其他内核也有类似分级，参考此优先级策略。
|
||
|
||
### 前端：Transition 内的 v-if/v-else 必须加 key
|
||
|
||
**这是 dev 模式的坑**。`<Transition mode="out-in">` 内的 `v-if`/`v-else` 分支如果缺 `:key`，Vue 3.5.x dev 模式下会触发 `__vnode` 写入竞态，导致：
|
||
|
||
- 控制台报错 `Cannot set properties of null (setting '__vnode')`
|
||
- vnode 树损坏，所有事件派发失效（按钮点击没反应）
|
||
- **build 模式不报错**（生产构建剥除了 `__vnode` instrumentation），容易漏掉
|
||
|
||
**约定**：`<Transition>` 内所有分支（v-if/v-else-if/v-else）都必须加 `:key`，即使是原生 div 也要加。
|
||
|
||
```vue
|
||
<Transition name="fade" mode="out-in">
|
||
<ComponentA v-if="cond" key="a" />
|
||
<div v-else key="empty">占位</div>
|
||
</Transition>
|
||
```
|
||
|
||
`ModuleContainer.vue` 和 `ProxyModule.vue` 的 Progress 区块已修复，新模块开发时注意。
|
||
|
||
### 前端：模块内 Tabs 顶部固定模式
|
||
|
||
模块根容器用 `h-full overflow-hidden flex flex-col`，Tabs 用 `flex-1 min-h-0 flex flex-col`，TabsList 加 `shrink-0`，TabsContent 加 `flex-1 min-h-0 overflow-y-auto`：
|
||
|
||
```vue
|
||
<div class="h-full p-6 overflow-hidden flex flex-col">
|
||
<Tabs v-model="tab" class="flex-1 min-h-0 flex flex-col">
|
||
<TabsList class="shrink-0">...</TabsList>
|
||
<TabsContent value="x" class="flex-1 min-h-0 overflow-y-auto">...</TabsContent>
|
||
</Tabs>
|
||
</div>
|
||
```
|
||
|
||
这样 TabsList 固定在顶部，只有 TabsContent 滚动。`min-h-0` 是 flex 子元素 overflow 生效的关键，不能省。
|
||
|
||
### 前端：Tauri 事件监听需在 store 中管理生命周期
|
||
|
||
`proxyStore.ts` 的 `installKernel` 确立了模式：
|
||
|
||
- 监听在方法调用时注册，`finally` 块中取消
|
||
- 用模块级变量保存 `UnlistenFn`，避免重复注册
|
||
- 错误事件由后端保证 emit（前端不重复弹 toast，统一由 watch 处理）
|
||
|
||
```typescript
|
||
let progressUnlisten: UnlistenFn | null = null
|
||
const installKernel = async () => {
|
||
if (!progressUnlisten) {
|
||
progressUnlisten = await listen<Progress>('xxx-progress', (e) => {
|
||
progress.value = e.payload
|
||
})
|
||
}
|
||
try {
|
||
await invoke('xxx_command')
|
||
} finally {
|
||
if (progressUnlisten) {
|
||
progressUnlisten()
|
||
progressUnlisten = null
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 前端：窗口隐藏前 blur 焦点
|
||
|
||
TitleBar 的关闭按钮实际是 `hide()` 到托盘。webview 快速隐藏时浏览器 `mouseleave` 可能不触发，导致从托盘恢复后按钮仍显示 hover 高亮。
|
||
|
||
**修复**：`hide()` 前调用 `document.activeElement.blur()`，并监听 `onFocusChanged` 在窗口重新获得焦点时再 blur 一次。新模块若有类似的"隐藏窗口"操作（如全局快捷键隐藏），同样需要 blur。
|
||
|
||
### 前端：浮动标签切换器（TabsList 滚动遮挡时在 TitleBar 显示）
|
||
|
||
模块详情页内容滚动时，顶部 `TabsList` 会被 `TitleBar` 遮挡，导致用户必须滚回顶部才能切换 Tab。已抽取通用 composable `src/lib/use-module-tabs.ts` 自动处理。
|
||
|
||
**接入方式**（任何使用 Tabs 的模块都可用，代理/下载器模块已接入）：
|
||
|
||
```ts
|
||
// 模块 <script setup> 顶部
|
||
import { useModuleTabs } from '@/lib/use-module-tabs'
|
||
|
||
const activeTab = ref('overview')
|
||
const tabsListRef = useModuleTabs(activeTab, [
|
||
{ value: 'overview', label: '概览' },
|
||
{ value: 'settings', label: '设置' }
|
||
])
|
||
```
|
||
|
||
```vue
|
||
<!-- 模板中给 TabsList 包一层带 ref 的 div -->
|
||
<Tabs v-model="activeTab">
|
||
<div ref="tabsListRef">
|
||
<TabsList>...</TabsList>
|
||
</div>
|
||
<TabsContent .../>
|
||
</Tabs>
|
||
```
|
||
|
||
**工作原理**：
|
||
- composable 内部在 `onMounted` 时注册标签到 `moduleTabsStore`，`onUnmounted` 时注销
|
||
- 用 `IntersectionObserver`（`rootMargin: '-44px 0px 0px 0px'` 裁剪 TitleBar 高度）监听 TabsList 可见性
|
||
- 滚动遮挡时 `TitleBar` 中"Thing"标题右侧自动显示浮动切换按钮（带淡入+左滑动画）
|
||
- 双向 watch 同步本地 `activeTab` 与 store，用户点击 TitleBar 浮动按钮也能切换模块内 Tab
|
||
|
||
**约束**：TitleBar 高度固定 40px（h-10），composable 已用 44px 裁剪（含 4px 缓冲）；store 是单例，一个模块同一时间只能注册一组标签。
|
||
|
||
### 前端：内核路径用 %APPDATA% 简化显示
|
||
|
||
内核路径较长（如 `C:\Users\xxx\AppData\Roaming\thing.lfeng.me\proxy\cores\mihomo.exe`），展示时用 `%APPDATA%` 替换前缀，并提供复制完整路径 / 在文件夹中显示两个按钮。代理和下载器模块的内核管理区块已采用此模式。
|
||
|
||
```ts
|
||
import { appDataDir } from '@tauri-apps/api/path'
|
||
|
||
const appDataPath = ref('')
|
||
onMounted(async () => {
|
||
try { appDataPath.value = await appDataDir() } catch {}
|
||
})
|
||
|
||
const pathDisplay = computed(() => {
|
||
const p = store.kernel?.path
|
||
if (!p) return ''
|
||
if (appDataPath.value && p.toLowerCase().startsWith(appDataPath.value.toLowerCase())) {
|
||
return '%APPDATA%' + p.slice(appDataPath.value.length)
|
||
}
|
||
return p
|
||
})
|
||
```
|
||
|
||
`<title>` 放完整路径，显示文本用 `pathDisplay`，复制时复制完整路径。
|
||
|
||
### 前端：任务历史持久化（下载器模块模式）
|
||
|
||
下载引擎在进程内运行，状态通过 `engine_state.json` 持久化到磁盘。前端 store 的做法：
|
||
|
||
- `onMounted` 时调用 `store.init()`，一次性加载 status/settings/extensionInfo/tasks
|
||
- 通过 Tauri 事件 `download-progress`、`download-complete`、`download-added` 实时更新任务状态
|
||
- 引擎在 `Storage::new` 时自动创建数据目录，`save` 时兜底重建父目录，避免路径不存在错误
|
||
|
||
此模式适用于任何"引擎在进程内运行、状态需持久化"的场景。
|
||
|
||
### 前端：轻量设置 Dialog（替代独立 Tab）
|
||
|
||
模块设置项较多时，传统做法是单独开一个"设置"Tab。但任务页工具栏需要快速调整少量核心设置（如下载目录、并发数），切到设置 Tab 再切回来体验割裂。
|
||
|
||
**模式**：在任务工具栏放一个"下载设置"按钮，点击弹出 Dialog，包含核心设置项（与设置页共用 `store.settings`），保存时调用 `handleSaveSettings`（引擎立即应用新配置，无需重启）并自动关闭弹窗。完整设置仍保留在"设置"Tab。
|
||
|
||
适用场景：需要在任务页快速调整的少量高频设置；若设置项不多，可完全用 Dialog 替代设置 Tab。
|
||
|
||
### 后端：opener 插件 scope 限制与绕过
|
||
|
||
`tauri-plugin-opener` 的 `opener:allow-open-path` 权限默认 **无 scope**，IPC `open_path` 命令会拒绝任何路径并报错 `Not allowed to open path`。
|
||
|
||
**解决方案**：在 Rust 端写一个自定义命令，用 `OpenerExt::opener().open_path()` 直接调用（绕过 IPC scope 检查）：
|
||
|
||
```rust
|
||
use tauri_plugin_opener::OpenerExt;
|
||
|
||
#[tauri::command]
|
||
pub fn my_open_dir(app: AppHandle, path: String) -> Result<(), String> {
|
||
let p = std::path::Path::new(&path);
|
||
if !p.exists() {
|
||
return Err(format!("路径不存在: {}", path));
|
||
}
|
||
app.opener().open_path(path, None::<&str>).map_err(|e| e.to_string())
|
||
}
|
||
```
|
||
|
||
在 `lib.rs` 的 `invoke_handler` 中注册，前端通过 `invoke('my_open_dir', { path })` 调用。下载器模块的"打开下载目录"已采用此方案。
|
||
|
||
### 前端：剩余时间（ETA）可读化
|
||
|
||
下载卡片直接显示 `(total-completed)/speed` 会得到 `17.217666215634114 B` 这种难懂的字节数。应格式化为时间：
|
||
|
||
```ts
|
||
const formatEta = (seconds: number): string => {
|
||
if (!isFinite(seconds) || seconds <= 0) return ''
|
||
if (seconds < 60) return `剩余 ${Math.ceil(seconds)} 秒`
|
||
if (seconds < 3600) {
|
||
const m = Math.floor(seconds / 60)
|
||
const s = Math.ceil(seconds % 60)
|
||
return `剩余 ${m} 分 ${s} 秒`
|
||
}
|
||
const h = Math.floor(seconds / 3600)
|
||
const m = Math.ceil((seconds % 3600) / 60)
|
||
return `剩余 ${h} 小时 ${m} 分`
|
||
}
|
||
```
|
||
|
||
`getEta(task) = (totalLength - completedLength) / downloadSpeed`，speed≤0 时返回 0（不显示）。
|
||
|
||
### 前端：状态统计用 Badge 替代纯文本
|
||
|
||
下载任务工具栏的速度/活跃/等待/已完成数量，以及代理概览页的内核状态/版本，从纯文本改为 `Badge variant="secondary"` 或带颜色的 `Badge`（绿色已安装/红色未安装），视觉更醒目。新模块的状态展示建议统一用 Badge。
|
||
|
||
### 后端：应用退出清理（单一出口）
|
||
|
||
退出清理已收敛到 `lib.rs` 的 `RunEvent::ExitRequested` 分支（P0-1/V7）：`quit_app` 命令与托盘退出项都只触发 `app.exit(0)`，清理逻辑（`cleanup_on_exit` + `stop_all`）只在该分支执行一次。新增管理子进程的模块时，在 `ExitRequested` 分支注册自己的 `cleanup_on_exit` 即可，不要在命令或托盘路径重复清理。
|