rust-rpa 0.1.5-beta.6 → 0.1.6

package/README.md

@@ -216,7 +216,7 @@ 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.auto_size` 为 true 时在 Windows 高 DPI 下自动缩放到逻辑像素尺寸
+- `captureImage(options?: CaptureImageOptions): Promise<ImageData>` - 截取窗口图像；可选 `options.size` 指定目标宽高并自动缩放；`options.from` 为 `'screen'` 时截取窗口所在显示器整屏；`options.region` 指定仅截取逻辑像素区域；`options.autoSize` 为 true 时在 Windows 高 DPI 下自动缩放到逻辑像素尺寸
 
 ### Monitor 类
 
@@ -282,9 +282,10 @@ const primary = monitors.find(m => m.isPrimary());
 
 **findIcon 参数：**
 - `template: ImageData` - 模板图片（要查找的图标）
-- `options: MatchOptions` - 可选的匹配选项对象
-  - `threshold: number` - 匹配阈值 (0.0-1.0)，默认 0.8
-  - `regions: Array<{x, y, width, height}>` - 可选的搜索区域列表，默认为空（全图搜索）
+- `options?: MatchOptions` - 可选的匹配选项对象
+  - `threshold?: number` - 匹配阈值 (0.0-1.0)，默认 0.8
+  - `regions?: Array<{x, y, width, height}>` - 可选的搜索区域列表，默认为空（全图搜索）
+    - 区域可超出图片边界，会自动裁剪为与图片的交集范围进行查找
 
 **MatchOptions 说明：**
 
@@ -343,7 +344,7 @@ interface CaptureImageOptions {
   // 以下仅对 Window.captureImage 有效：
   from?: 'window' | 'screen';  // 默认 'window' 截窗口；'screen' 截窗口所在显示器整屏（可配合 getBounds 与 image.crop 裁剪出窗口）
   region?: CaptureRegion | null;  // 仅截取该逻辑像素区域，不填则截全图
-  auto_size?: boolean | null;     // 为 true 时在 Windows 存在 DPI 缩放时自动将图像缩放到逻辑像素宽高（与 getSize/getBounds 一致）
+  autoSize?: boolean | null;     // 为 true 时在 Windows 存在 DPI 缩放时自动将图像缩放到逻辑像素宽高（与 getSize/getBounds 一致）
 }
 ```
 
@@ -353,7 +354,7 @@ interface CaptureImageOptions {
 
 #### 静态方法
 
-- `Mouse.moveTo(x, y): Promise<void>` - 移动鼠标到指定坐标
+- `Mouse.moveTo(x, y, duration?): Promise<void>` - 移动鼠标到指定坐标。**duration** 可选，移动动画持续时间（秒），默认为 0（瞬间移动）。如果设置 > 0，鼠标将以平滑动画的方式移动到目标点，动画过程中会触发 mouseMove 事件
 - `Mouse.click(button?): Promise<void>` - 点击鼠标。**button** 可选，可用枚举 `MouseButton.Left` / `MouseButton.Right` 或字符串 `'left'` / `'right'` 等，默认左键
 - `Mouse.doubleClick(button?): Promise<void>` - 双击鼠标，button 同上
 - `Mouse.down(button?): Promise<void>` - 按下鼠标按钮，button 同上
@@ -542,7 +543,7 @@ if (windows.length > 0) {
 
 **截图选项**：`captureImage(options?)` 接受可选对象 `CaptureImageOptions`：
 - `size?: { width, height }`：截取后缩放到指定宽高，不传则返回原始尺寸。
-- **Window 专用**：`from?: 'window' | 'screen'` 默认截窗口，设为 `'screen'` 可截窗口所在显示器整屏再配合 `getBounds()` 与 `image.crop()` 裁剪；`region?: { x, y, width, height }` 仅截取该逻辑像素区域；`auto_size?: true` 在 Windows 高 DPI 下自动将图像缩放到逻辑像素宽高（与 `getSize`/`getBounds` 一致）。
+- **Window 专用**：`from?: 'window' | 'screen'` 默认截窗口，设为 `'screen'` 可截窗口所在显示器整屏再配合 `getBounds()` 与 `image.crop()` 裁剪；`region?: { x, y, width, height }` 仅截取该逻辑像素区域；`autoSize?: true` 在 Windows 高 DPI 下自动将图像缩放到逻辑像素宽高（与 `getSize`/`getBounds` 一致）。
 
 ### 输入自动化
 
@@ -550,7 +551,8 @@ if (windows.length > 0) {
 const { Mouse, MouseButton, Keyboard, Key } = require('rust-rpa');
 
 // 鼠标操作
-await Mouse.moveTo(100, 200);              // 移动鼠标
+await Mouse.moveTo(100, 200);              // 瞬间移动鼠标
+await Mouse.moveTo(100, 200, 0.5);         // 平滑动画移动，持续 0.5 秒
 await Mouse.click(MouseButton.Left);       // 左键点击
 await Mouse.click(MouseButton.Right);      // 右键点击
 await Mouse.doubleClick();                 // 双击
@@ -746,13 +748,30 @@ npm test
 
 ## 更新日志
 
+### 0.1.6
+
+#### BREAKCHANGE
+
+- **Windows 平台鼠标坐标统一为逻辑像素**: `Mouse.moveTo()` 和 `Mouse.position()` 现在统一使用逻辑像素坐标，与 `Window.getBounds()` 等 API 保持一致
+  - 此前 Windows 平台上鼠标操作使用物理像素，在高 DPI 缩放环境下与窗口坐标不一致
+  - 现在 Windows 平台会自动处理 DPI 缩放，传入和返回的坐标均为逻辑像素
+  - macOS 平台不受影响（原本就使用逻辑像素）
+
+
 ### 0.1.5
 
 #### 功能
+- **`Mouse.moveTo` 增强**: 新增可选 `duration` 参数，支持平滑动画移动
+  - `duration` 为移动动画持续时间（秒），默认为 0（瞬间移动）
+  - 当 `duration > 0` 时，鼠标以平滑动画方式移动到目标点，使用 easeInOutCubic 缓动函数
+  - 动画过程中会触发 mouseMove 事件，网页等应用可正常响应鼠标移动
+- **`findIcon` 参数优化**: `options` 参数中的 `threshold` 和 `regions` 字段均改为可选
+  - `threshold` 不传时默认使用 0.8
+  - `regions` 中的区域可超出图片边界，会自动裁剪为与图片的交集范围进行查找
 - **Window.captureImage 选项 `from`**：新增 `'window'`（默认）与 `'screen'`。设为 `'screen'` 时先截取窗口所在显示器整屏，再自动裁剪为当前窗口与显示器的交集区域（超出显示器的部分忽略）。
 - **Window.captureImage 选项 `region`**：新增可选参数，仅截取指定逻辑像素区域 `{ x, y, width, height }`，不填则截取全图。
-- **Window.captureImage 选项 `auto_size`**：新增可选参数。为 `true` 时，在 Windows 存在 DPI 缩放的情况下自动将图像缩放到逻辑像素宽高（与 `getSize`/`getBounds` 一致）。
-- **CaptureImageOptions 处理顺序**：内部先执行 `auto_size`（缩放到逻辑像素），再执行 `region`（按逻辑像素裁剪），最后应用 `size`（若有）。启用 `auto_size` 后，`region` 与逻辑像素坐标一一对应。
+- **Window.captureImage 选项 `auto`**：新增可选参数。为 `true` 时，在 Windows 存在 DPI 缩放的情况下自动将图像缩放到逻辑像素宽高（与 `getSize`/`getBounds` 一致）。
+- **CaptureImageOptions 处理顺序**：内部先执行 `autoSize`（缩放到逻辑像素），再执行 `region`（按逻辑像素裁剪），最后应用 `size`（若有）。启用 `autoSize` 后，`region` 与逻辑像素坐标一一对应。
 
 ### 0.1.4
 

package/index.d.ts

@@ -29,8 +29,8 @@ export interface ImageMetadata {
 }
 /** 匹配选项 */
 export interface MatchOptionsJs {
-  /** 匹配阈值 (0.0-1.0)，低于此值视为未找到 */
-  threshold: number
+  /** 匹配阈值 (0.0-1.0)，低于此值视为未找到，默认 0.8 */
+  threshold?: number
   /** 匹配区域列表，若为空则在整个图片中匹配 */
   regions?: Array<MatchRegion>
 }
@@ -147,8 +147,13 @@ export interface MousePosition {
 
 /** Mouse 类 - 鼠标控制 */
 export declare class Mouse {
-  /** 移动鼠标到指定坐标 */
-  static moveTo(x: number, y: number): Promise<void>
+  /**
+   * 移动鼠标到指定坐标
+   * @param x - 目标 x 坐标
+   * @param y - 目标 y 坐标
+   * @param duration - 可选，移动动画持续时间（秒）。默认为 0，表示瞬间移动。如果设置 > 0，鼠标将以平滑动画的方式移动到目标点
+   */
+  static moveTo(x: number, y: number, duration?: number | null): Promise<void>
   /** 点击鼠标按钮。button 可选，可用 MouseButton.Left / 'left' 等，默认左键 */
   static click(button?: MouseButtonType | null): Promise<void>
   /** 双击鼠标按钮。button 取值同 click */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-rpa",
-  "version": "0.1.5-beta.6",
+  "version": "0.1.6",
   "description": "Rust-based RPA automation library for Node.js",
   "type": "commonjs",
   "main": "index.js",