rust-rpa 0.2.5 → 0.2.6-beta.2

package/README.md

@@ -205,7 +205,7 @@ main();
 - `setBounds(bounds)` - 设置窗口边界
 - `toJSON()` - 转为 JSON 对象
 - `captureImage(options?)` - 截图
-- `watchChanges(options?, callback)` - 监听窗口内容变化；返回 `WindowWatcher`（`stop()` / `isRunning()`），回调收到变化后的 `ImageData` 或 `null`（见 `sendImage` 选项）
+- `watchChanges(options?, callback)` - 监听窗口内容变化；返回 `WindowWatcher`（`stop()` / `isRunning()`），回调无参数；`stableFrames` 选项可过滤光标闪烁等瞬态变化
 - `recognizeText(options?)` - OCR 识别文字
 - `findText(text, options?)` - 查找文字
 - `findIcon(template, options?)` - 查找图标
@@ -591,6 +591,17 @@ if (targetWindow) {
 
 ## 更新日志
 
+### 0.2.6
+
+#### 新功能
+
+- **Window.watchChanges 新增 `stableFrames` 选项**: 支持过滤光标闪烁等瞬态变化，仅检测真实内容变化
+  - `stableFrames: 0`（默认）- 检测到变化即触发回调，最快响应
+  - `stableFrames: N` - 需连续 N 帧与上一帧相比均有变化才触发回调
+  - 过滤光标闪烁原理：光标闪烁 ON→OFF 一次变化、OFF→OFF 无变化则计数重置，无法连续 N 帧；而真实内容变化（新消息出现）会持续与旧基线不同，连续 N 帧均有变化
+  - 推荐 `stableFrames: 2` 可过滤大多数光标闪烁
+  - 示例：`window.watchChanges({ threshold: 0.02, stableFrames: 2 }, callback)`
+
 ### 0.2.5
 
 #### 改进
@@ -625,7 +636,7 @@ if (targetWindow) {
 
 #### 新功能
 
-- **Window.watchChanges（窗口内容变化监听）**: 后台线程降采样对比相邻帧，超过阈值才截取完整窗口图并回调；支持 `threshold`、`from`（`window`/`screen`）、`region`、`captureSize`、`sendImage`；返回 `WindowWatcher` 可 `stop()`。
+- **Window.watchChanges（窗口内容变化监听）**: 后台线程降采样对比相邻帧，超过阈值才截取完整窗口图并回调；支持 `threshold`、`from`（`window`/`screen`）、`region`、`captureSize`；返回 `WindowWatcher` 可 `stop()`。
 
 ### 0.2.3
 

package/index.d.ts

@@ -271,11 +271,22 @@ export interface WindowWatchOptionsJs {
   region?: CaptureRegion | null
   /** 检测到变化后传递给回调的截图目标尺寸 */
   captureSize?: CaptureSizeJs | null
-  /** 是否在回调中传递截图图像，默认 true */
-  sendImage?: boolean
+  /**
+   * 变化确认帧数，默认 0
+   *
+   * - 0 表示检测到变化即触发回调（最快响应）
+   * - 大于 0 时，需连续 N 帧与上一帧相比均有变化才触发回调
+   *
+   * 适用于过滤光标闪烁等瞬态变化：光标闪烁在 ON/OFF 间交替，
+   * ON→OFF 一次变化、OFF→OFF 无变化则计数重置，无法连续 N 帧；
+   * 而真实内容变化（如新消息出现）会持续与旧基线不同，
+   * 连续 N 帧均有变化，通过确认。
+   * 推荐 stableFrames=2 可过滤大多数光标闪烁。
+   */
+  stableFrames?: number
 }
 /** 窗口内容变化监听的回调函数签名 */
-export type WindowChangeCallback = (image: ImageData | null) => void
+export type WindowChangeCallback = () => void
 /** 窗口变化监听器句柄，用于停止监听 */
 export interface WindowWatcher {
   /** 停止监听，释放底层资源 */
@@ -1295,57 +1306,48 @@ export declare class Window {
    */
   clickIcon(template: ImageData, options?: WindowWaitOptions | null): Promise<ClickResult>
   /**
-   * 监听窗口内容变化，当检测到变化时自动截取最新截图并传递给回调函数
+   * 监听窗口内容变化，当检测到变化时触发回调函数
    * 
-   * 底层使用降采样差异检测，仅在窗口内容发生变化时才截取完整图像，
+   * 底层使用降采样差异检测，仅在窗口内容发生变化时才触发回调，
    * 资源开销远低于定时轮询截图。
    * 
    * @param options 监听选项（可选）
-   * @param callback 变化时的回调函数，sendImage=true 时接收 ImageData，否则接收 null
+   * @param callback 变化时的回调函数（无参数）
    * @returns WindowWatcher 句柄，调用 stop() 可停止监听
    * 
    * @example
    * ```javascript
-   * // 场景 1：需要获取变化后的截图
+   * // 场景 1：监听窗口变化
    * const watcher = targetWindow.watchChanges(
    *   { threshold: 0.02, from: 'window' },
-   *   (image) => {
-   *     console.log(`窗口变化，新截图: ${image.width}x${image.height}`);
-   *     sendToExternalService(image);
+   *   () => {
+   *     console.log('窗口内容发生了变化');
    *   }
    * );
    * ```
    * 
    * @example
    * ```javascript
-   * // 场景 2：只需要知道窗口有变化，不需要截图（更低开销）
+   * // 场景 2：仅监听窗口的特定区域
    * const watcher = targetWindow.watchChanges(
-   *   { sendImage: false },
-   *   (image) => {
-   *     console.log('窗口内容发生了变化');
-   *     onWindowChanged();
+   *   { 
+   *     region: { x: 100, y: 200, width: 400, height: 300 },
+   *   },
+   *   () => {
+   *     console.log('指定区域内容发生了变化');
    *   }
    * );
    * ```
    * 
    * @example
    * ```javascript
-   * // 场景 3：仅监听窗口的特定区域
+   * // 场景 3：忽略光标闪烁，仅检测真实内容变化
    * const watcher = targetWindow.watchChanges(
-   *   { 
-   *     region: { x: 100, y: 200, width: 400, height: 300 },
-   *     captureSize: { width: 800, height: 600 },
-   *     sendImage: true
-   *   },
-   *   (image) => {
-   *     processScreenshot(image);
+   *   { threshold: 0.02, stableFrames: 2 },
+   *   () => {
+   *     console.log('窗口内容发生持久变化');
    *   }
    * );
-   * 
-   * // 停止监听
-   * setTimeout(() => {
-   *   watcher.stop();
-   * }, 60000);
    * ```
    */
   watchChanges(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-rpa",
-  "version": "0.2.5",
+  "version": "0.2.6-beta.2",
   "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.5",
-    "@alibot/rust-rpa-win32-ia32-msvc": "0.2.5",
-    "@alibot/rust-rpa-darwin-x64": "0.2.5",
-    "@alibot/rust-rpa-darwin-arm64": "0.2.5"
+    "@alibot/rust-rpa-win32-x64-msvc": "0.2.6-beta.2",
+    "@alibot/rust-rpa-win32-ia32-msvc": "0.2.6-beta.2",
+    "@alibot/rust-rpa-darwin-x64": "0.2.6-beta.2",
+    "@alibot/rust-rpa-darwin-arm64": "0.2.6-beta.2"
   }
 }