taskbar-progress 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,153 @@
+# taskbar-progress
+
+> **Windows 任务栏进度条（Taskbar Progress）的最小 C++ Addon**
+>
+> ✅ 体积小（~50KB）
+> ✅ 无 Electron 依赖
+> ✅ CommonJS / pkg 友好
+> ✅ Windows 10 / 11 稳定
+
+---
+
+## ✅ 效果
+
+| 状态 | 表现 |
+|---|---|
+| 🟩 正常进度 | 绿色进度条填充 |
+| 🌀 不确定进度 | 滚动绿光动画 |
+| 🔴 错误状态 | 红色进度条 |
+| ⬜ 清除进度 | 恢复正常图标 |
+
+---
+
+## 📦 安装
+
+```bash
+npm install taskbar-progress
+```
+
+> **前置要求**：Windows + Visual Studio Build Tools + Python（用于 `node-gyp` 编译）
+
+---
+
+## 🚀 快速使用
+
+```js
+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` 自动编译）：
+
+```bash
+npm install -g node-gyp
+node-gyp configure
+node-gyp build
+```
+
+编译产物：`build/Release/taskbar_progress.node`
+
+---
+
+## 📦 pkg 打包支持
+
+在 `package.json` 中声明需要打包的 native 文件：
+
+```json
+{
+  "pkg": {
+    "assets": ["node_modules/taskbar-progress/build/Release/taskbar_progress.node"]
+  }
+}
+```
+
+代码中已内置路径自适应逻辑，pkg 环境下会自动定位到正确的 `.node` 文件路径。
+
+---
+
+## 📝 注意事项
+
+- **仅支持 Windows 平台**（会自动跳过其他平台）
+- 需要程序在任务栏有可见按钮（控制台窗口或 GUI 宿主）
+- 在 Windows Terminal 下效果可能不如经典控制台（conhost）明显
+- 如果从隐藏窗口或纯后台服务调用，可能无法显示进度条
+
+---
+
+## 🔧 故障排查
+
+### 编译失败
+
+确保已安装：
+- [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)（勾选「C++ 桌面开发」）
+- [Python 3.x](https://www.python.org/)（`node-gyp` 依赖）
+
+然后执行：
+
+```bash
+npm config set msvs_version 2022
+npm rebuild
+```
+
+### 运行时无效果
+
+1. 确认程序是从**有窗口的上下文**运行的（非后台服务）
+2. 检查 `process.platform === 'win32'` 是否为 `true`
+3. 尝试从开始菜单快捷方式启动（而非直接双击 exe）
+
+---
+
+## 📄 License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskbar-progress",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "任务栏进度",
   "main": "index.js",
   "keywords": [