rust-rpa 0.2.6 → 0.2.7

package/README.md

@@ -205,7 +205,7 @@ main();
 - `setBounds(bounds)` - 设置窗口边界
 - `toJSON()` - 转为 JSON 对象
 - `captureImage(options?)` - 截图
-- `watchChanges(options?, callback)` - 监听窗口内容变化；返回 `WindowWatcher`（`stop()` / `isRunning()` / `changeOptions()`）；启动时先建基线**不**调回调，仅在检测到相对上一帧的变化时调用 `callback(changeRatio)`（约 0–1；两帧缓冲区长度不一致时为 `1`）；`regions` 可指定多个逻辑像素监控区域
+- `watchChanges(options?, callback)` - 监听窗口内容变化；返回 `WindowWatcher`（`stop()` / `isRunning()` / `changeOptions()`）；启动时先建基线**不**调回调，仅在检测到相对上一帧的变化时调用 `callback(info)`（`info` 含 `changeRatio` 变化比例和 `changedPixels` 估算变化像素数）；`regions` 可指定多个逻辑像素监控区域；`minChangedPixels` 可按原图逻辑像素数控制触发门槛；`minPixelDiff` 可设置单像素最小通道差异（默认 30）过滤截图噪声
 - `recognizeText(options?)` - OCR 识别文字
 - `findText(text, options?)` - 查找文字
 - `findIcon(template, options?)` - 查找图标
@@ -591,6 +591,21 @@ if (targetWindow) {
 
 ## 更新日志
 
+### 0.2.7
+
+#### 新功能
+
+- **Window.watchChanges 新增 `minChangedPixels` 参数**: 支持按原图逻辑像素数控制变化触发，与 `threshold` 为 AND 关系
+  - `minChangedPixels: 0`（默认）- 不使用此条件，仅靠 `threshold` 控制
+  - `minChangedPixels > 0` - 估算的原图逻辑像素变化数须 >= 该值才触发回调
+  - 示例：`{ threshold: 0.001, minChangedPixels: 500 }` 表示变化比例超过 0.1% **且** 至少 500 个逻辑像素变化才触发
+- **Window.watchChanges 新增 `minPixelDiff` 参数**: 单像素最小通道差异（0-255），默认 30，用于过滤截图捕获噪声
+  - `minPixelDiff: 30`（默认）- R/G/B 任一通道差值 ≥ 30 才算“变化”，有效过滤截图噪声（通常差值 1-10）
+  - `minPixelDiff: 0` - 任意微小差异都计入（最敏感，但噪声也会触发）
+  - `minPixelDiff: 1` - 任意像素差异都计入（精确字节比较）
+  - 示例：`{ threshold: 0, minChangedPixels: 2, minPixelDiff: 30 }` 过滤噪声同时保持对光标闪烁等微小变化的灵敏度
+- **Window.watchChanges 回调参数改为对象**: `callback(info)`，`info` 为 `{ changeRatio, changedPixels }`，其中 `changeRatio` 为相邻两帧像素变化比例（约 0.0–1.0），`changedPixels` 为估算的原图逻辑像素变化数；**启动首帧不触发回调**（仅建基线）；两帧缓冲区长度不一致时 `changeRatio` 为 `1`、`changedPixels` 为 `4294967295`。
+
 ### 0.2.6
 
 #### 行为调整

package/index.d.ts

@@ -258,16 +258,41 @@ export interface WindowWatchOptionsJs {
    * - 大于 0.0 时，仅当像素变化比例超过阈值才触发回调
    */
   threshold?: number
+  /**
+   * 最小变化像素数（逻辑像素），默认 0（不使用）
+   *
+   * - 0 表示不使用此条件，仅靠 threshold 控制
+   * - 大于 0 时，估算的原图逻辑像素变化数须 >= 该值才触发回调
+   * - 与 threshold 为 AND 关系：两者均满足时才触发
+   */
+  minChangedPixels?: number
+  /**
+   * 单像素最小通道差异（0-255），默认 30，用于过滤截图噪声
+   *
+   * - 仅当像素的 R/G/B 任一通道差值 >= 该值才算“变化”
+   * - 设为 0 则任意微小差异都计入（最敏感，但噪声也会触发）
+   * - 设为 1 则任意像素差异都计入（精确字节比较）
+   */
+  minPixelDiff?: number
   /** 图片来源：'window'（默认）或 'screen' */
   from?: 'window' | 'screen'
   /** 仅在指定多个区域检测变化（逻辑像素，相对窗口）；不填或空数组表示全窗口 */
   regions?: Array<CaptureRegion> | null
 }
+/**
+ * 窗口内容变化回调信息
+ */
+export interface WindowChangeInfo {
+  /** 降采样相邻帧对比得到的像素变化比例，约 0.0–1.0；帧尺寸不一致时为 `1` */
+  changeRatio: number
+  /** 估算的原图逻辑像素变化数；帧尺寸不一致时为 `4294967295` (u32::MAX) */
+  changedPixels: number
+}
 /**
  * 窗口内容变化回调（启动时先采一帧建基线，不调用本回调；之后仅在检测到相对上一帧的变化时调用）
- * @param changeRatio 降采样相邻帧对比得到的像素变化比例，约 0.0–1.0；帧尺寸不一致时为 `1`
+ * @param info 变化详情，含 `changeRatio`（变化比例）和 `changedPixels`（估算变化像素数）
  */
-export type WindowChangeCallback = (changeRatio: number) => void
+export type WindowChangeCallback = (info: WindowChangeInfo) => void
 /** 窗口变化监听器句柄，用于停止监听 */
 export interface WindowWatcher {
   /** 停止监听，释放底层资源 */
@@ -1306,8 +1331,8 @@ export declare class Window {
    * // 场景 1：监听窗口变化
    * const watcher = targetWindow.watchChanges(
    *   { threshold: 0.02, from: 'window' },
-   *   (changeRatio) => {
-   *     console.log('窗口内容发生了变化', changeRatio);
+   *   (info) => {
+   *     console.log('窗口内容发生了变化', info.changeRatio, info.changedPixels);
    *   }
    * );
    * ```
@@ -1322,8 +1347,8 @@ export declare class Window {
    *       { x: 0, y: 0, width: 200, height: 80 },
    *     ],
    *   },
-   *   (changeRatio) => {
-   *     console.log('指定区域内容发生了变化', changeRatio);
+   *   (info) => {
+   *     console.log('指定区域内容发生了变化', info.changeRatio, info.changedPixels);
    *   }
    * );
    * ```
@@ -1333,8 +1358,8 @@ export declare class Window {
    * // 场景 3：提高阈值减少微小变化触发
    * const watcher = targetWindow.watchChanges(
    *   { threshold: 0.02 },
-   *   (changeRatio) => {
-   *     console.log('窗口内容发生持久变化', changeRatio);
+   *   (info) => {
+   *     console.log('窗口内容发生持久变化', info.changeRatio);
    *   }
    * );
    * watcher.changeOptions({ threshold: 0.05 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-rpa",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Rust-based RPA automation library for Node.js",
   "type": "commonjs",
   "main": "index.js",
@@ -67,9 +67,9 @@
     "commander": "^14.0.3"
   },
   "optionalDependencies": {
-    "@alibot/rust-rpa-win32-x64-msvc": "0.2.6",
-    "@alibot/rust-rpa-win32-ia32-msvc": "0.2.6",
-    "@alibot/rust-rpa-darwin-x64": "0.2.6",
-    "@alibot/rust-rpa-darwin-arm64": "0.2.6"
+    "@alibot/rust-rpa-win32-x64-msvc": "0.2.7",
+    "@alibot/rust-rpa-win32-ia32-msvc": "0.2.7",
+    "@alibot/rust-rpa-darwin-x64": "0.2.7",
+    "@alibot/rust-rpa-darwin-arm64": "0.2.7"
   }
 }