congsh
8e9d108995
Tauri 2 + React：任务列表、快捷方式、番茄钟、系统托盘、钉子穿透模式等。 Co-authored-by: Cursor <cursoragent@cursor.com>
153 lines
5.2 KiB
Markdown
153 lines
5.2 KiB
Markdown
# DeskFloat · 桌面透明浮动工具栏
|
||
|
||
一个资源占用极低的 Windows 桌面浮动工具栏，使用 **Tauri 2 + React + TypeScript** 实现。
|
||
|
||
主要功能：
|
||
|
||
- **任务列表**：增删改查、勾选完成、拖拽排序、未完成数量徽标
|
||
- **自定义快捷按钮**：支持 4 种执行类型
|
||
- `url` — 用系统默认浏览器打开网页
|
||
- `app` — 启动可执行文件（支持参数 / 工作目录）
|
||
- `cmd` — 运行 `cmd.exe /C ...` 命令（隐藏控制台）
|
||
- `powershell` — 运行 PowerShell 命令（隐藏控制台）
|
||
- **番茄钟**：工作/休息双阶段倒计时 + 系统通知 + 可调时长
|
||
- **全局快捷键**：显示/隐藏窗口、快速新建任务、番茄钟开始暂停
|
||
- **系统托盘**：任务栏右下角托盘图标，右键菜单可显示/隐藏/退出
|
||
- **设置**：背景透明度、始终置顶、开机自启、数据目录跳转
|
||
- **持久化**：JSON 文件存于 `%APPDATA%\com.deskfloat.app\data.json`，写入有 300ms 防抖
|
||
|
||
预期资源占用：内存约 50–80MB，安装包 < 10MB。
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 层 | 技术 |
|
||
|---|---|
|
||
| 桌面壳 | Tauri 2.x（Rust 主进程 + 系统 WebView） |
|
||
| 前端 | React 18 + TypeScript + Vite |
|
||
| 状态 | Zustand（轻量） |
|
||
| 图标 | lucide-react（按需引入） |
|
||
| 拖拽 | @dnd-kit |
|
||
| 后端能力 | tauri-plugin-{fs, opener, shell, notification, global-shortcut, autostart} |
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
deskTopFloat/
|
||
├── src-tauri/ # Rust 后端
|
||
│ ├── src/
|
||
│ │ ├── main.rs # 入口
|
||
│ │ ├── lib.rs # 注册插件 / 命令
|
||
│ │ ├── storage.rs # JSON 读写
|
||
│ │ ├── runner.rs # 快捷方式执行
|
||
│ │ └── commands.rs # invoke 命令导出
|
||
│ ├── icons/ # 应用图标（由 mmx 生成 + tauri icon 打包）
|
||
│ ├── capabilities/default.json
|
||
│ ├── Cargo.toml
|
||
│ └── tauri.conf.json
|
||
├── src/ # 前端
|
||
│ ├── App.tsx
|
||
│ ├── main.tsx
|
||
│ ├── api/tauri.ts # invoke 封装
|
||
│ ├── store/
|
||
│ │ ├── types.ts # 类型定义
|
||
│ │ └── useAppStore.ts # Zustand store（含防抖落盘）
|
||
│ ├── hooks/useHotkeys.ts # 全局快捷键注册
|
||
│ ├── components/Toolbar/ # 工具栏外壳
|
||
│ ├── modules/
|
||
│ │ ├── tasks/ # 任务列表
|
||
│ │ ├── shortcuts/ # 自定义快捷按钮
|
||
│ │ ├── pomodoro/ # 番茄钟
|
||
│ │ └── settings/ # 设置面板
|
||
│ └── styles/global.css
|
||
├── package.json
|
||
├── vite.config.ts
|
||
├── tsconfig.json
|
||
└── PROGRESS.md # 开发进度
|
||
```
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
- **Node.js** 18+（实测 22.22.0）
|
||
- **Rust** 1.77+（实测 1.93.0）
|
||
- **Windows 10/11**，需安装 WebView2（Win10 1803+ 自带）
|
||
- 推荐安装 **Visual Studio Build Tools**（含 MSVC C++ 工具链，Tauri 编译需要）
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```powershell
|
||
# 安装前端依赖
|
||
npm install
|
||
|
||
# 开发模式（启动 Vite + Tauri 主窗口）
|
||
npm run tauri:dev
|
||
|
||
# 生产构建（生成 MSI 安装包 + NSIS 安装程序）
|
||
npm run tauri:build
|
||
```
|
||
|
||
构建产物路径：`src-tauri\target\release\bundle\msi\*.msi` 与 `src-tauri\target\release\bundle\nsis\*-setup.exe`。
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
### 默认全局快捷键
|
||
|
||
| 快捷键 | 功能 |
|
||
|---|---|
|
||
| `Ctrl + Alt + \`` | 显示 / 隐藏主窗口 |
|
||
| `Ctrl + Alt + T` | 调出窗口并定位到任务输入框（快速记一条任务） |
|
||
| `Ctrl + Alt + P` | 番茄钟 开始 / 暂停 |
|
||
|
||
可在 **设置面板** 中自定义。
|
||
|
||
### 系统托盘（退出应用）
|
||
|
||
主窗口无标题栏关闭按钮。要结束程序请使用 **任务栏右下角托盘区** 的 DeskFloat 图标：
|
||
|
||
| 操作 | 效果 |
|
||
|------|------|
|
||
| **右键** → 显示工具栏 | 显示浮动工具栏 |
|
||
| **右键** → 隐藏工具栏 | 隐藏浮动工具栏（进程仍在） |
|
||
| **右键** → **退出** | 完全关闭应用 |
|
||
| **左键单击** 托盘图标 | 切换显示 / 隐藏 |
|
||
|
||
若触发系统级「关闭窗口」，也会改为隐藏到托盘，不会直接退出。
|
||
|
||
### 快捷方式编辑
|
||
|
||
工具栏上的"快捷区"显示已配置按钮：
|
||
- **左键** 单击 → 执行
|
||
- **右键** 单击 → 打开管理面板（编辑/删除）
|
||
- **"+"** 号 → 新增
|
||
|
||
类型示例：
|
||
|
||
```jsonc
|
||
{ "type": "url", "target": "https://github.com" }
|
||
{ "type": "app", "target": "C:\\Program Files\\Cursor\\Cursor.exe", "args": [] }
|
||
{ "type": "cmd", "target": "echo hello && pause", "cwd": "D:\\projects" }
|
||
{ "type": "powershell", "target": "Get-Process | Sort CPU -Desc | Select -First 5" }
|
||
```
|
||
|
||
### 数据存储
|
||
|
||
所有数据均写入 `%APPDATA%\com.deskfloat.app\data.json`，可在设置面板 → "数据目录" 直接跳转。
|
||
|
||
---
|
||
|
||
## 开发须知
|
||
|
||
- 前端写入 store 后会自动防抖 300ms 整体落盘
|
||
- Rust 侧执行子进程时会 `CREATE_NO_WINDOW`（0x0800_0000），避免黑色控制台一闪而过
|
||
- 透明度由 CSS 变量 `--bg-opacity` 控制，实时响应设置面板滑块
|
||
- 全局快捷键通过 `tauri-plugin-global-shortcut`，修改后会重新注册
|