rust-rpa 0.2.4 → 0.2.6-beta.1

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()`），回调收到变化后的 `ImageData` 或 `null`（见 `sendImage` 选项）；`stableFrames` 选项可过滤光标闪烁等瞬态变化
 - `recognizeText(options?)` - OCR 识别文字
 - `findText(text, options?)` - 查找文字
 - `findIcon(template, options?)` - 查找图标
@@ -591,6 +591,47 @@ 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
+
+#### 改进
+
+- **Window.watchChanges 优化**: `threshold` 参数默认值改为 `0.0`，并优化为 `0` 时跳过图像对比
+  - `threshold: 0`（默认）- 跳过像素对比，每次轮询直接触发回调，最低延迟
+  - `threshold > 0` - 执行降采样对比，变化比例超过阈值才触发回调
+  - 适用于已知窗口会变化、需要立即获取截图的场景
+
+### 0.2.5
+
+#### 新功能
+
+- **findText / waitText / clickText 新增 `index` 参数**: 支持选择第几个匹配的文字结果
+  - `index` 默认为 `0`，返回第一个匹配结果
+  - 正数表示第 n 个（从 0 开始）：`index: 1` 返回第二个
+  - 负数表示倒数第 n 个：`index: -1` 返回最后一个，`index: -2` 返回倒数第二个
+  - 超出匹配数量范围时返回 `null`
+  - 适用场景：页面中存在多个相同文字，需要点击特定位置
+  - 示例：`findText('确定', { index: 1 })` 查找第二个「确定」，`clickText('确定', { index: -2 })` 点击倒数第二个「确定」
+
+#### 类型定义更新
+
+- `FindTextOptions` 新增 `index?: number` 字段
+- `WindowFindTextOptions` 新增 `index?: number` 字段
+- `MonitorFindTextOptions` 新增 `index?: number` 字段
+- `WindowWaitOptions` 新增 `index?: number` 字段
+- `MonitorWaitOptions` 新增 `index?: number` 字段
+- `WaitOptions` 新增 `index?: number` 字段
+
 ### 0.2.4
 
 #### 新功能

package/index.d.ts

@@ -60,6 +60,8 @@ export interface FindTextOptions {
   regions?: Array<MatchRegion>
   /** 排除文字，若同一行中包含此文字则排除该匹配结果 */
   notText?: string
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个 */
+  index?: number
 }
 /** 文字查找选项（Window 专用） */
 export interface WindowFindTextOptions {
@@ -73,6 +75,8 @@ export interface WindowFindTextOptions {
    * - `'screen'`：截取窗口所在显示器的整屏
    */
   from?: 'window' | 'screen'
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个 */
+  index?: number
 }
 /** 文字查找选项（Monitor 专用） */
 export interface MonitorFindTextOptions {
@@ -80,6 +84,8 @@ export interface MonitorFindTextOptions {
   regions?: Array<MatchRegion>
   /** 排除文字，若同一行中包含此文字则排除该匹配结果 */
   notText?: string
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个 */
+  index?: number
 }
 /** 文字识别选项（ImageData 使用） */
 export interface RecognizeTextOptions {
@@ -118,6 +124,8 @@ export interface WindowWaitOptions {
    * - `'screen'`：截取窗口所在显示器的整屏
    */
   from?: 'window' | 'screen'
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个（仅用于 waitText/clickText） */
+  index?: number
 }
 /** 等待选项（Monitor 专用） */
 export interface MonitorWaitOptions {
@@ -129,6 +137,8 @@ export interface MonitorWaitOptions {
   threshold?: number
   /** 排除文字，若同一行中包含此文字则排除该匹配结果（仅用于 waitText/clickText） */
   notText?: string
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个（仅用于 waitText/clickText） */
+  index?: number
 }
 /** 等待选项（兼容旧代码，与 WindowWaitOptions 相同） */
 export interface WaitOptions {
@@ -146,6 +156,8 @@ export interface WaitOptions {
    * - `'screen'`：截取窗口所在显示器的整屏
    */
   from?: 'window' | 'screen'
+  /** 匹配索引，默认为 0（第一个匹配）。负数表示倒数：-1 最后一个，-2 倒数第二个（仅用于 waitText/clickText） */
+  index?: number
 }
 /** 图标匹配结果 */
 export interface MatchResult {
@@ -246,7 +258,12 @@ export interface CaptureSizeJs {
 }
 /** 窗口变化监听的选项 */
 export interface WindowWatchOptionsJs {
-  /** 变化检测的灵敏度阈值 (0.0-1.0)，默认 0.02 */
+  /**
+   * 变化检测的灵敏度阈值 (0.0-1.0)，默认 0.0
+   *
+   * - 0.0 表示跳过对比，每次轮询都触发回调（最敏感，最低延迟）
+   * - 大于 0.0 时，仅当像素变化比例超过阈值才触发回调
+   */
   threshold?: number
   /** 图片来源：'window'（默认）或 'screen' */
   from?: 'window' | 'screen'
@@ -256,6 +273,19 @@ export interface WindowWatchOptionsJs {
   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
@@ -1330,6 +1360,17 @@ export declare class Window {
    *   watcher.stop();
    * }, 60000);
    * ```
+   * 
+   * @example
+   * ```javascript
+   * // 场景 4：忽略光标闪烁，仅检测真实内容变化
+   * const watcher = targetWindow.watchChanges(
+   *   { threshold: 0.02, stableFrames: 2 },
+   *   (image) => {
+   *     console.log('窗口内容发生持久变化');
+   *   }
+   * );
+   * ```
    */
   watchChanges(
     options: WindowWatchOptionsJs | null | undefined,

package/package.json

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