deskTopFloat/README.md

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 编译需要）

---

快速开始

# 安装前端依赖
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 图标：

操作	效果
右键 → 显示工具栏	显示浮动工具栏
右键 → 隐藏工具栏	隐藏浮动工具栏（进程仍在）
右键 → 退出	完全关闭应用
左键单击 托盘图标	切换显示 / 隐藏

若触发系统级「关闭窗口」，也会改为隐藏到托盘，不会直接退出。

快捷方式编辑

工具栏上的"快捷区"显示已配置按钮：

• 左键 单击 → 执行
• 右键 单击 → 打开管理面板（编辑/删除）
• "+" 号 → 新增

类型示例：

{ "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，修改后会重新注册