taskbar-progress

Windows 任务栏进度条（Taskbar Progress）的最小 C++ Addon

✅ 体积小（~50KB） ✅ 无 Electron 依赖 ✅ CommonJS / pkg 友好 ✅ Windows 10 / 11 稳定

✅ 效果

| 状态 | 表现 | |---|---|---| | 🟩 正常进度 | 绿色进度条填充 | | 🌀 不确定进度 | 滚动绿光动画 | | 🔴 错误状态 | 红色进度条 | | ⬜ 清除进度 | 恢复正常图标 |

📦 安装

npm install taskbar-progress

前置要求：Windows + Visual Studio Build Tools + Python（用于 node-gyp 编译）

🚀 快速使用

const { setProgress, setIndeterminate, setError } = require('taskbar-progress');

// 设置 42% 进度
setProgress(0.42);

// 不确定进度（滚动动画）
setIndeterminate();

// 错误状态（红色）
setError();

// 清除进度条
setProgress(-1);

📖 API 文档

setProgress(value: number)

控制任务栏进度条的显示状态。

| 参数值 | 效果 | |---|---| | -1 | 清除进度条 | | 0.0 ~ 1.0 | 显示对应百分比的绿色进度条 | | >= 1.0 | 显示满格进度条 |

setIndeterminate()

显示不确定进度（滚动绿光动画），适用于无法预估剩余时间的场景。

setError()

显示错误状态（红色进度条），适用于任务失败的场景。

📁 目录结构

taskbar-progress/
├── package.json
├── binding.gyp
├── src/
│   └── taskbar.cc
├── index.js
└── README.md

⚙️ 手动编译

如果你需要自行编译（而非通过 npm install 自动编译）：

npm install -g node-gyp
node-gyp configure
node-gyp build

编译产物：build/Release/taskbar_progress.node

📦 pkg 打包支持

在 package.json 中声明需要打包的 native 文件：

{
  "pkg": {
    "assets": ["node_modules/taskbar-progress/build/Release/taskbar_progress.node"]
  }
}

代码中已内置路径自适应逻辑，pkg 环境下会自动定位到正确的 .node 文件路径。

📝 注意事项

• 仅支持 Windows 平台（会自动跳过其他平台）
• 需要程序在任务栏有可见按钮（控制台窗口或 GUI 宿主）
• 在 Windows Terminal 下效果可能不如经典控制台（conhost）明显
• 如果从隐藏窗口或纯后台服务调用，可能无法显示进度条

🔧 故障排查

编译失败

确保已安装：

• Visual Studio Build Tools（勾选「C++ 桌面开发」）
• Python 3.x（node-gyp 依赖）

然后执行：

npm config set msvs_version 2022
npm rebuild

运行时无效果

1. 确认程序是从有窗口的上下文运行的（非后台服务）
2. 检查 process.platform === 'win32' 是否为 true
3. 尝试从开始菜单快捷方式启动（而非直接双击 exe）
4. GUI 子系统：确保进程创建了非隐藏的顶层窗口（EnumWindows 能枚举到）

📄 License

MIT