rust-rpa 0.1.7 → 0.2.0-beta.0

package/README.md

@@ -14,6 +14,7 @@
 - 🖥️ **多显示器支持**: Monitor 类，支持多显示器设置
 - 📸 **屏幕截图**: 支持全屏和窗口截图，多种图片格式
 - 🔑 **权限管理**: Permission 类，自动检测并弹出系统权限授权对话框
+- 🔍 **OCR 文字识别**: 基于 PP-OCRv5_mobile 模型，支持中英日文字识别及文字位置查找
 
 ## 安装
 
@@ -216,7 +217,14 @@ const windows = Window.all();
 - `getBounds(): WindowBounds` - 获取窗口边界（位置和大小）
 - `setBounds(bounds): Promise<void>` - 设置窗口边界（位置和大小）
 - `toJSON(): WindowToJson` - 转为 JSON 可序列化对象
-- `captureImage(options?: CaptureImageOptions): Promise<ImageData>` - 截取窗口图像；可选 `options.size` 指定目标宽高并自动缩放；`options.from` 为 `'screen'` 时截取窗口所在显示器整屏；`options.region` 指定仅截取逻辑像素区域；`options.autoSize` 为 true 时在 Windows 高 DPI 下自动缩放到逻辑像素尺寸
+- `captureImage(options?: CaptureImageOptions): Promise<ImageData>` - 截取窗口图像；可选 `options.size` 指定目标宽高并自动缩放；`options.from` 为 `'screen'` 时截取窗口所在显示器整屏；`options.region` 指定仅截取逻辑像素区域；`options.autoSize` 默认为 `true`，在 Windows 高 DPI 下自动缩放到逻辑像素尺寸
+- `findIcon(template, options?): Promise<MatchResult>` - 在窗口截图中查找模板图标（先截图 autoSize=true，再执行模板匹配）
+- `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` 可指定查找区域
+- `waitIcon(template, options?): Promise<MatchResult>` - 等待指定图标出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域
+- `clickText(text, options?): Promise<void>` - 点击指定文字，先等待文字出现，然后点击文字中心点
+- `clickIcon(template, options?): Promise<void>` - 点击指定图标，先等待图标出现，然后点击图标中心点
 
 ### Monitor 类
 
@@ -243,7 +251,14 @@ const primary = monitors.find(m => m.isPrimary());
 - `height(): number` - 获取显示器高度
 - `scaleFactor(): number` - 获取缩放因子
 - `isPrimary(): boolean` - 是否主显示器
-- `captureImage(options?: CaptureImageOptions): Promise<ImageData>` - 截取显示器图像；可选 `options.size` 指定目标宽高并自动缩放
+- `captureImage(options?: CaptureImageOptions): Promise<ImageData>` - 截取显示器图像；可选 `options.size` 指定目标宽高并自动缩放；`options.autoSize` 默认为 `true`，在 Windows 高 DPI 下自动缩放到逻辑像素尺寸
+- `findIcon(template, options?): Promise<MatchResult>` - 在显示器截图中查找模板图标（先截图 autoSize=true，再执行模板匹配）
+- `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` 可指定查找区域
+- `waitIcon(template, options?): Promise<MatchResult>` - 等待指定图标出现，超时抛出错误；`options.timeout` 指定等待时间（默认 3000ms），`options.regions` 可指定查找区域
+- `clickText(text, options?): Promise<void>` - 点击指定文字，先等待文字出现，然后点击文字中心点
+- `clickIcon(template, options?): Promise<void>` - 点击指定图标，先等待图标出现，然后点击图标中心点
 
 ### ImageData 类
 
@@ -274,6 +289,8 @@ const primary = monitors.find(m => m.isPrimary());
 - `resize(width, height): Promise<ImageData>` - 缩放图像（使用 Lanczos3 高质量算法）
 - `grayscale(): Promise<ImageData>` - 转换为灰度图（使用标准加权算法：0.299R + 0.587G + 0.114B）
 - `findIcon(template, options?): Promise<MatchResult>` - 查找模板图标（模板匹配）
+- `recognizeText(): Promise<TextRecognitionResult[]>` - 识别图片中的文字（OCR）
+- `findText(text): Promise<TextRecognitionResult | null>` - 查找指定文字，找到返回位置信息，未找到返回 null（OCR）
 
 **数据访问**
 
@@ -344,7 +361,7 @@ interface CaptureImageOptions {
   // 以下仅对 Window.captureImage 有效：
   from?: 'window' | 'screen';  // 默认 'window' 截窗口；'screen' 截窗口所在显示器整屏（可配合 getBounds 与 image.crop 裁剪出窗口）
   region?: CaptureRegion | null;  // 仅截取该逻辑像素区域，不填则截全图
-  autoSize?: boolean | null;     // 为 true 时在 Windows 存在 DPI 缩放时自动将图像缩放到逻辑像素宽高（与 getSize/getBounds 一致）
+  autoSize?: boolean | null;     // 默认为 true，在 Windows 存在 DPI 缩放时自动将图像缩放到逻辑像素宽高（与 getSize/getBounds 一致）
 }
 ```
 
@@ -401,7 +418,32 @@ interface CaptureImageOptions {
 - `Permission.checkAccessibility(prompt?): boolean` - 检查辅助功能权限（鼠标、键盘、窗口操作等需要此权限）
 - `Permission.checkScreenCapture(prompt?): boolean` - 检查屏幕录制权限（截图功能需要此权限）
 
+### pause 函数
+
+暂停/等待指定时间的辅助函数。
+
+#### 函数签名
+
+- `pause(ms: number): Promise<void>` - 等待指定毫秒数
+
+```javascript
+const { pause } = require('rust-rpa');
+
+// 等待 1 秒
+await pause(1000);
+
+// 在操作之间添加延迟
+await Mouse.click('left');
+await pause(500);  // 等待 500ms
+await Keyboard.typeText('Hello');
+```
+
 **参数说明：**
+- `ms`：等待时间，单位为毫秒
+
+---
+
+**Permission 类参数说明：**
 - `prompt`（可选，默认 `true`）：无权限时是否自动弹出系统授权对话框（仅 macOS 生效）
 
 **平台行为差异：**
@@ -606,11 +648,75 @@ await Clipboard.pasteImage('image.png');
 await Clipboard.pasteFile('/path/to/file.pdf');
 ```
 
-### 图像处理
+### OCR 文字识别
+
+利用 PP-OCRv5_mobile 模型，支持在 **ImageData**、**Window** 和 **Monitor** 上直接执行 OCR。
 
 ```javascript
-const fs = require('fs');
-const { Monitor, ImageData } = require('rust-rpa');
+const { Monitor, Window, ImageData } = require('rust-rpa');
+
+// --- ImageData 正中 OCR ---
+const image = await ImageData.fromFile('screenshot.png');
+
+// 识别图片中所有文字
+const results = await image.recognizeText();
+for (const result of results) {
+  console.log(`文字: ${result.text}`);
+  console.log(`  位置: (${result.x}, ${result.y}), 大小: ${result.width}x${result.height}`);
+  console.log(`  置信度: ${(result.confidence * 100).toFixed(1)}%`);
+}
+
+// 查找指定文字
+const found = await image.findText('确定');
+if (found) {
+  console.log(`找到"确定"在: (${found.x}, ${found.y})`);
+}
+
+// --- Monitor 上 OCR ---
+const monitors = Monitor.all();
+const monitorResults = await monitors[0].recognizeText();
+console.log(`显示器上数到 ${monitorResults.length} 条文字`);
+
+// 在显示器上查找文字
+const monitorFound = await monitors[0].findText('文件');
+if (monitorFound) {
+  console.log(`在显示器上找到"文件": (${monitorFound.x}, ${monitorFound.y})`);
+}
+
+// --- Window 上 OCR ---
+const windows = Window.all();
+const targetWindow = windows.find(w => w.appName().includes('Chrome'));
+if (targetWindow) {
+  // 识别窗口中的文字（内部先截图）
+  const windowResults = await targetWindow.recognizeText();
+  console.log(`Chrome 窗口中有 ${windowResults.length} 条文字`);
+  
+  // 在窗口中查找指定文字
+  const windowFound = await targetWindow.findText('搜索');
+  if (windowFound) {
+    console.log(`在窗口中找到"搜索": (${windowFound.x}, ${windowFound.y})`);
+  }
+}
+```
+
+**TextRecognitionResult 类型：**
+```typescript
+interface TextRecognitionResult {
+  text: string;         // 识别到的文字
+  x: number;            // 文字区块左上角 x 坐标（像素）
+  y: number;            // 文字区块左上角 y 坐标（像素）
+  width: number;        // 文字区块宽度（像素）
+  height: number;       // 文字区块高度（像素）
+  confidence: number;   // 置信度（0.0-1.0）
+}
+```
+
+> **注意**: OCR 功能需要预先下载模型文件到 `models/` 目录下。模型文件分别为:
+> - `PP-OCRv5_mobile_det.mnn` — 文字检测模型（4.7M）
+> - `PP-OCRv5_mobile_rec.mnn` — 文字识别模型（16M）
+> - `ppocr_keys_v5.txt` — 字符集
+
+
 
 // 方式 1: 从截图获取图片
 const monitors = Monitor.all();
@@ -741,13 +847,58 @@ npm test
 - [x] 图像保存到文件
 - [x] 剪贴板操作
 - [x] 窗口操作（置顶、移动、调整大小、父进程查询）
-- [ ] 定位文字findText(text, {prompt: '', model: '', timeout: number})
-- [ ] 等待文字、图标、指定时间
-- [ ] 点击文字、图标等操作
+- [x] OCR 文字识别（基于 PP-OCRv5_mobile）
+- [x] 文字位置查找（findText）
+- [x] 等待文字、图标出现（waitText/waitIcon）
+- [x] 点击文字、图标（clickText/clickIcon）
 - [ ] 进程管理
 
 ## 更新日志
 
+### 0.2.0
+
+#### 新功能
+
+- **OCR 文字识别**: 新增 `recognizeText()` 和 `findText()` 方法
+  - 基于 PP-OCRv5_mobile 模型（检测模型 4.7M + 识别模型 16M）
+  - 支持中文、英文、日文识别
+  - `ImageData.recognizeText()` - 识别图片中的所有文字，返回文字列表及其位置信息
+  - `ImageData.findText(text, options?)` - 在图片中查找指定文字，返回匹配文字的位置信息；`options.regions` 可指定查找区域列表以提升性能
+- **Window 类增强**: 新增 `findIcon()`、`recognizeText()`、`findText()`、`waitText()`、`waitIcon()`、`clickText()`、`clickIcon()` 方法
+  - 所有方法内部先执行 `captureImage({ autoSize: true })`，然后在截图上执行对应操作
+  - `Window.findIcon(template, options?)` - 在窗口截图中查找图标
+  - `Window.recognizeText()` - 识别窗口中的文字
+  - `Window.findText(text, options?)` - 在窗口中查找指定文字
+  - `Window.waitText(text, options?)` - 等待指定文字出现，超时抛出错误
+  - `Window.waitIcon(template, options?)` - 等待指定图标出现，超时抛出错误
+  - `Window.clickText(text, options?)` - 点击指定文字
+  - `Window.clickIcon(template, options?)` - 点击指定图标
+- **Monitor 类增强**: 新增 `findIcon()`、`recognizeText()`、`findText()`、`waitText()`、`waitIcon()`、`clickText()`、`clickIcon()` 方法
+  - 所有方法内部先执行 `captureImage({ autoSize: true })`，然后在截图上执行对应操作
+  - `Monitor.findIcon(template, options?)` - 在显示器截图中查找图标
+  - `Monitor.recognizeText()` - 识别显示器截图中的文字
+  - `Monitor.findText(text, options?)` - 在显示器截图中查找指定文字
+  - `Monitor.waitText(text, options?)` - 等待指定文字出现，超时抛出错误
+  - `Monitor.waitIcon(template, options?)` - 等待指定图标出现，超时抛出错误
+  - `Monitor.clickText(text, options?)` - 点击指定文字
+  - `Monitor.clickIcon(template, options?)` - 点击指定图标
+
+#### BREAKCHANGE
+
+- **`captureImage` 的 `autoSize` 默认值改为 `true`**: `Monitor.captureImage()` 和 `Window.captureImage()` 的 `autoSize` 选项默认值从 `false` 改为 `true`
+  - 现在默认自动将图像缩放到逻辑像素尺寸，与 `getBounds()`/`getSize()` 返回的坐标一致
+  - 如需物理像素图像，需显式传入 `autoSize: false`
+  - 影响范围：所有依赖截图尺寸的逻辑（OCR、模板匹配等）现在默认使用逻辑坐标
+
+#### 技术详情
+
+- 使用 `ocr-rs` crate 提供 PaddleOCR 功能
+- 使用 MNN 推理框架，提供高性能本地推理
+- 支持 GPU 加速（如果可用）
+- 模型文件需要自行下载放置在 `models/` 目录
+
+## 更新日志
+
 ### 0.1.7
 
 #### BREAKCHANGE
@@ -761,6 +912,22 @@ npm test
   - 此前 Windows 上正数向上滚动，与 macOS 相反
   - 现在双平台方向一致：正数向下，负数向上
 
+#### 功能
+
+- **所有输入操作自动添加延迟**: `Mouse` 和 `Keyboard` 类的所有操作方法现在自动在返回前添加 50ms 延迟
+  - 包括：`moveTo`, `click`, `doubleClick`, `down`, `up`, `scroll`
+  - 包括：`Keyboard.click`, `typeText`, `down`, `up`, `sequence`
+  - 确保系统有足够时间处理操作，避免后续操作立即执行导致失败
+- **剪贴板操作自动添加延迟**: `Clipboard` 类的写入和粘贴方法现在自动添加 50ms 延迟
+  - 包括：`writeText`, `writeImage`, `writeFile`, `paste`
+  - 确保剪贴板内容写入完成后再执行后续操作
+- **窗口操作自动添加延迟**: `Window` 类的状态修改方法现在自动添加 50ms 延迟
+  - 包括：`bringToFront`, `setBounds`
+  - 确保窗口状态变更完成后再执行后续操作
+- **`clickText`/`clickIcon` 返回点击坐标**: `Window.clickText()` 和 `Window.clickIcon()` 现在返回 `ClickResult` 对象
+  - 返回 `{ x, y }` 表示实际点击的屏幕坐标
+  - 便于调试和验证点击位置
+
 ### 0.1.6
 
 #### BREAKCHANGE