rust-rpa 0.2.0-beta.7 → 0.2.0-beta.8

package/README.md

@@ -211,7 +211,7 @@ const windows = Window.all();
 - `setBounds(bounds): Promise<void>` - 设置窗口边界（位置和大小）
 - `toJSON(): WindowToJson` - 转为 JSON 可序列化对象
 - `captureImage(options?: CaptureImageOptions): Promise<ImageData>` - 截取窗口图像；可选 `options.size` 指定目标宽高并自动缩放；`options.from` 为 `'screen'` 时截取窗口所在显示器整屏；`options.region` 指定仅截取逻辑像素区域；`options.autoSize` 默认为 `true`，在 Windows 高 DPI 下自动缩放到逻辑像素尺寸
-- `findIcon(template, options?): Promise<MatchResult>` - 在窗口截图中查找模板图标（先截图 autoSize=true，再执行模板匹配）
+- `findIcon(template, options?): Promise<MatchResult | null>` - 在窗口截图中查找模板图标（先截图 autoSize=true，再执行模板匹配），找到返回 MatchResult，未找到返回 null
 - `recognizeText(): Promise<TextRecognitionResult[]>` - 识别窗口截图中的文字（先截图 autoSize=true，再执行 OCR）
 - `findText(text, options?): Promise<TextRecognitionResult | null>` - 在窗口截图中查找指定文字，找到返回位置信息，未找到返回 null（先截图 autoSize=true，再执行 OCR）；`options.regions` 可指定查找区域列表以提升性能
 - `waitText(text, options?): Promise<TextRecognitionResult>` - 等待指定文字出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域
@@ -245,7 +245,7 @@ const primary = monitors.find(m => m.isPrimary());
 - `scaleFactor(): number` - 获取缩放因子
 - `isPrimary(): boolean` - 是否主显示器
 - `captureImage(options?: CaptureImageOptions): Promise<ImageData>` - 截取显示器图像；可选 `options.size` 指定目标宽高并自动缩放；`options.autoSize` 默认为 `true`，在 Windows 高 DPI 下自动缩放到逻辑像素尺寸
-- `findIcon(template, options?): Promise<MatchResult>` - 在显示器截图中查找模板图标（先截图 autoSize=true，再执行模板匹配）
+- `findIcon(template, options?): Promise<MatchResult | null>` - 在显示器截图中查找模板图标（先截图 autoSize=true，再执行模板匹配），找到返回 MatchResult，未找到返回 null
 - `recognizeText(): Promise<TextRecognitionResult[]>` - 识别显示器截图中的文字（先截图 autoSize=true，再执行 OCR）
 - `findText(text, options?): Promise<TextRecognitionResult | null>` - 在显示器截图中查找指定文字，找到返回位置信息，未找到返回 null（先截图 autoSize=true，再执行 OCR）；`options.regions` 可指定查找区域列表以提升性能
 - `waitText(text, options?): Promise<TextRecognitionResult>` - 等待指定文字出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域
@@ -281,7 +281,7 @@ const primary = monitors.find(m => m.isPrimary());
 - `crop(x, y, width, height): Promise<ImageData>` - 裁剪图像
 - `resize(width, height): Promise<ImageData>` - 缩放图像
 - `grayscale(): Promise<ImageData>` - 转换为灰度图
-- `findIcon(template, options?): Promise<MatchResult>` - 查找模板图标
+- `findIcon(template, options?): Promise<MatchResult | null>` - 查找模板图标，找到返回 MatchResult，未找到返回 null
 - `recognizeText(): Promise<TextRecognitionResult[]>` - 识别图片中的文字
 - `findText(text): Promise<TextRecognitionResult | null>` - 查找指定文字
 
@@ -315,16 +315,27 @@ const primary = monitors.find(m => m.isPrimary());
 - 大多数情况使用默认参数即可：`findIcon(template)`
 - 需要调整灵敏度时指定阈值：`findIcon(template, { threshold: 0.9 })`
 - 在特定区域查找可提高性能：`findIcon(template, { threshold: 0.8, regions: [...] })`
+- **返回值处理**：未找到时返回 `null`，使用时需检查返回值
+  ```javascript
+  const result = await image.findIcon(template);
+  if (result) {
+    console.log(`找到图标: (${result.x}, ${result.y})`);
+  } else {
+    console.log('未找到图标');
+  }
+  ```
 
 **MatchResult 类型：**
 ```typescript
 interface MatchResult {
   found: boolean;      // 是否找到匹配
   score: number;       // 相似度分数 (0.0-1.0)
-  x: number;           // 匹配位置 x 坐标
-  y: number;           // 匹配位置 y 坐标
+  x: number;           // 匹配位置 x 坐标（逻辑屏幕坐标，可直接用于 Mouse.moveTo）
+  y: number;           // 匹配位置 y 坐标（逻辑屏幕坐标，可直接用于 Mouse.moveTo）
   width: number;       // 模板宽度
   height: number;      // 模板高度
+  relX: number;        // 相对于当前窗口/屏幕左上角的 x 坐标
+  relY: number;        // 相对于当前窗口/屏幕左上角的 y 坐标
 }
 ```
 
@@ -698,11 +709,13 @@ if (targetWindow) {
 ```typescript
 interface TextRecognitionResult {
   text: string;         // 识别到的文字
-  x: number;            // 文字区块左上角 x 坐标（像素）
-  y: number;            // 文字区块左上角 y 坐标（像素）
+  x: number;            // 文字区块左上角 x 坐标（逻辑屏幕坐标，可直接用于 Mouse.moveTo）
+  y: number;            // 文字区块左上角 y 坐标（逻辑屏幕坐标，可直接用于 Mouse.moveTo）
   width: number;        // 文字区块宽度（像素）
   height: number;       // 文字区块高度（像素）
   confidence: number;   // 置信度（0.0-1.0）
+  relX: number;         // 相对于当前窗口/屏幕左上角的 x 坐标
+  relY: number;         // 相对于当前窗口/屏幕左上角的 y 坐标
 }
 ```
 
@@ -796,11 +809,21 @@ interface TextRecognitionResult {
   - 影响范围：所有依赖截图尺寸的逻辑（OCR、模板匹配等）现在默认使用逻辑坐标
   - rpa部分命令简化
 
-#### 技术详情
-
-- 使用 MNN 推理框架，提供高性能本地推理
-- 支持 GPU 加速（如果可用）
-- OCR 模型内置于 npm 包中，开箱即用
+#### API 变更
+
+- **`findIcon` 返回值调整**: `findIcon()` 方法在未找到匹配时现在返回 `null` 而非 `{ found: false, ... }` 对象
+  - 找到匹配: 返回 `MatchResult` 对象 `{ found: true, score, x, y, width, height }`
+  - 未找到匹配: 返回 `null`
+  - 影响范围: `ImageData.findIcon()`, `Window.findIcon()`, `Monitor.findIcon()`
+  - 迁移指南: 使用 `if (result) { ... }` 或 `if (result !== null) { ... }` 检查返回值
+  ```javascript
+  const result = await image.findIcon(template);
+  if (result) {
+    console.log(`找到图标: (${result.x}, ${result.y}), 置信度: ${result.score}`);
+  } else {
+    console.log('未找到图标');
+  }
+  ```
 
 ### 0.1.7
 

package/bin/rpa.js

@@ -361,14 +361,13 @@ image.command('find-icon').description('在图片中查找图标')
       options.regions = [{ x, y, width: w, height: h }];
     }
     const result = await img.findIcon(tmpl, options);
-    if (result.found) {
+    if (result) {
       console.log(c.green(`找到图标`));
       console.log(`位置: (${result.x}, ${result.y})`);
       console.log(`大小: ${result.width}x${result.height}`);
       console.log(`相似度: ${(result.score * 100).toFixed(2)}%`);
     } else {
       console.log(c.yellow('未找到图标'));
-      console.log(`最高相似度: ${(result.score * 100).toFixed(2)}%`);
       process.exit(1);
     }
   });
@@ -448,7 +447,7 @@ monitor.command('find-icon').description('在显示器截图中查找图标')
       options.regions = [{ x, y, width: w, height: h }];
     }
     const result = await mon.findIcon(tmpl, options);
-    if (result.found) {
+    if (result) {
       console.log(c.green(`找到图标`));
       console.log(`屏幕位置: (${result.x}, ${result.y})`);
       console.log(`大小: ${result.width}x${result.height}`);
@@ -624,7 +623,7 @@ window.command('find-icon').description('在窗口截图中查找图标')
       options.regions = [{ x, y, width: w, height: h }];
     }
     const result = await win.findIcon(tmpl, options);
-    if (result.found) {
+    if (result) {
       console.log(c.green(`找到图标`));
       console.log(`窗口内位置: (${result.x}, ${result.y})`);
       console.log(`大小: ${result.width}x${result.height}`);

package/index.d.ts

@@ -59,22 +59,26 @@ export interface MatchResult {
   found: boolean
   /** 相似度分数 (0.0-1.0) */
   score: number
-  /** 匹配位置 x 坐标 */
+  /** 匹配位置 x 坐标（逻辑屏幕坐标，可直接用于 Mouse.moveTo） */
   x: number
-  /** 匹配位置 y 坐标 */
+  /** 匹配位置 y 坐标（逻辑屏幕坐标，可直接用于 Mouse.moveTo） */
   y: number
   /** 模板宽度 */
   width: number
   /** 模板高度 */
   height: number
+  /** 相对于当前窗口/屏幕左上角的 x 坐标 */
+  relX: number
+  /** 相对于当前窗口/屏幕左上角的 y 坐标 */
+  relY: number
 }
 /** 文字识别结果 */
 export interface TextRecognitionResult {
   /** 识别出的文字内容 */
   text: string
-  /** 文字区域左上角 x 坐标 */
+  /** 文字区域左上角 x 坐标（逻辑屏幕坐标，可直接用于 Mouse.moveTo） */
   x: number
-  /** 文字区域左上角 y 坐标 */
+  /** 文字区域左上角 y 坐标（逻辑屏幕坐标，可直接用于 Mouse.moveTo） */
   y: number
   /** 文字区域宽度 */
   width: number
@@ -82,6 +86,10 @@ export interface TextRecognitionResult {
   height: number
   /** 识别置信度 (0.0-1.0) */
   confidence: number
+  /** 相对于当前窗口/屏幕左上角的 x 坐标 */
+  relX: number
+  /** 相对于当前窗口/屏幕左上角的 y 坐标 */
+  relY: number
 }
 /** 截图时可选的目标尺寸，配置后会将截取到的图像缩放到指定宽高 */
 export interface CaptureSize {
@@ -107,6 +115,10 @@ export interface ClickResult {
   x: number
   /** 点击的 y 坐标（屏幕坐标） */
   y: number
+  /** 相对于当前窗口/屏幕左上角的 x 坐标 */
+  relX: number
+  /** 相对于当前窗口/屏幕左上角的 y 坐标 */
+  relY: number
 }
 /** captureImage 的选项对象，便于后续扩展更多参数 */
 export interface CaptureImageOptions {
@@ -424,7 +436,7 @@ export declare class ImageData {
   /** 缩放图片（异步） */
   resize(newWidth: number, newHeight: number): Promise<ImageData>
   /** 在图片中查找模板图标（异步） */
-  findIcon(template: ImageData, options?: MatchOptionsJs | undefined | null): Promise<MatchResult>
+  findIcon(template: ImageData, options?: MatchOptionsJs | undefined | null): Promise<MatchResult | null>
   /**
    * 识别图片中的文字（异步）
    *
@@ -549,12 +561,12 @@ export declare class Monitor {
    * const monitors = Monitor.all();
    * const template = await ImageData.fromFile('button.png');
    * const result = await monitors[0].findIcon(template);
-   * if (result.found) {
+   * if (result) {
    *   console.log(`Found at: (${result.x}, ${result.y})`);
    * }
    * ```
    */
-  findIcon(template: ImageData, options?: MatchOptionsJs | undefined | null): Promise<MatchResult>
+  findIcon(template: ImageData, options?: MatchOptionsJs | undefined | null): Promise<MatchResult | null>
   /**
    * 识别显示器截图中的文字（异步）
    *
@@ -933,7 +945,7 @@ export declare class Window {
    *
    * # Returns
    *
-   * 返回 Promise<MatchResult>
+   * 返回 Promise<MatchResult | null>，找到返回结果，未找到返回 null
    *
    * # Example
    *
@@ -944,12 +956,12 @@ export declare class Window {
    * const window = windows.find(w => w.appName().includes('Chrome'));
    * const template = await ImageData.fromFile('button.png');
    * const result = await window.findIcon(template);
-   * if (result.found) {
+   * if (result) {
    *   console.log(`Found at: (${result.x}, ${result.y})`);
    * }
    * ```
    */
-  findIcon(template: ImageData, options?: MatchOptionsJs | undefined | null): Promise<MatchResult>
+  findIcon(template: ImageData, options?: MatchOptionsJs | undefined | null): Promise<MatchResult | null>
   /**
    * 识别窗口中的文字（异步）
    *

package/package.json

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