@bettergi/utils 0.0.3 → 0.0.5

package/README.md

@@ -10,7 +10,7 @@ npm install @bettergi/utils
 
 ### 图文识别
 
-> 对 RecognitionObject 代码的封装，对于简单的 OCR 操作，无需写复杂的代码。
+> 对 RecognitionObject 代码的封装，对于简单的找图、找字操作，不再需要编写复杂的代码。
 
 ```ts
 import {
@@ -23,13 +23,13 @@ import {
 } from "@bettergi/utils";
 
 // 在整个画面内搜索图片，找不到返回 undefined
-const f1 = findImage("assets/关闭.png");
+const i1 = findImage("assets/关闭.png");
 
 // 在指定方向上搜索图片，找不到返回 undefined
-const f2 = findImageInDirection("assets/关闭.png", "north-east");
+const i2 = findImageInDirection("assets/关闭.png", "north-east");
 
 // 在指定区域内搜索图片，找不到返回 undefined
-const f3 = findImageWithinBounds("assets/关闭.png", 960, 0, 960, 1080);
+const i3 = findImageWithinBounds("assets/关闭.png", 960, 0, 960, 1080);
 
 // 在整个画面内搜索文本（不包含、忽略大小写），找不到返回 undefined
 const t1 = findText("购买", false, true);
@@ -41,41 +41,78 @@ const t2 = findTextInDirection("师傅", true, true, "east");
 const t3 = findTextWithinBounds("确认", false, true, 960, 540, 960, 540);
 ```
 
-### 行为
+### 行为流程
 
-> 对脚本工作流中常见行为的抽象，例如：等待 XXX 完成/出现/消失。
+> 对脚本开发过程中常见工作流的抽象，例如：等待 XXX 完成/出现/消失。
 
 ```ts
 import { findImageInDirection, waitUntil } from "@bettergi/utils";
 
 // 等待直到找不到[关闭按钮] 或 5秒后超时，每隔1秒检查一次，期间按 Esc 键
 const done = await waitUntil(
-  () => findImageInDirection("assets/关闭.png", "north-east") !== undefined,
+  () => findImageInDirection("assets/关闭.png", "north-east") === undefined,
   5000,
   1000,
   () => keyPress("ESCAPE")
 );
-if (!done) throw new Error("关闭页面");
+if (!done) throw new Error("关闭页面超时");
 ```
 
-### 存储
+### 鼠标操作
 
-> 对象数据持久化，通过代理实现自动存储。可以无感知地读取/更新数据，而无需考虑如何持久化。
+> 对常见鼠标操作的封装，如鼠标滚动、拖拽等。
+
+```ts
+import {
+  mouseScrollDown,
+  mouseScrollDownLines,
+  mouseScrollUp,
+  mouseScrollUpLines,
+  mouseSlide,
+  mouseSlideX,
+  mouseSlideY
+} from "@bettergi/utils";
+
+// 鼠标滚轮向上滚动 175 像素
+await mouseScrollUp(175);
+
+// 鼠标滚轮向下滚动 175 像素
+await mouseScrollDown(175);
+
+// 鼠标滚轮向上滚动 99 行，行高 175（默认：背包物品行高）
+await mouseScrollUpLines(99);
+
+// 鼠标滚轮向下滚动 1 行，行高 115（自定义：商店物品行高）
+await mouseScrollDownLines(1, 115);
+
+// 鼠标从 (745, 610) 拖拽到 (1280, 610)
+await mouseSlide(745, 610, 1280, 610);
+
+// 鼠标从 (745, 610) 向右拖拽 435 像素
+await mouseSlideX(745, 610, 435);
+
+// 鼠标从 (1290, 140) 向下拖拽 175 像素
+await mouseSlideY(1290, 140, 175);
+```
+
+### 数据存储
+
+> 对象数据持久化，通过 Proxy 实现自动存储。从而可以无感知地读取/更新数据，而无需考虑如何持久化。
 
 ```ts
 import { useStore } from "@bettergi/utils";
 
 // 创建/读取存储对象，保存到存储文件 store/state.json 中
-// 通过Proxy来实现：对存储对象的操作会同步保存到存储文件
 const state = useStore<{ lastUsedTime?: number; count: number }>("state");
 if (state?.lastUsedTime) {
   log.info(`欢迎回来！上次使用时间：${state.lastUsedTime}，计数器已累计至：${state.count}`);
 }
 try {
+  // 模拟脚本运行期间状态的变化
   for (let i = 0; i < Math.floor(Math.random() * 100); i++) {
-    state.count = (state.count || 0) + 1; // 同步保存到文件
+    state.count = (state.count || 0) + 1; // 自动同步保存到文件
   }
 } finally {
-  state.lastUsedTime = Date.now(); // 同步保存到文件
+  state.lastUsedTime = Date.now(); // 自动同步保存到文件
 }
 ```

package/dist/mouse.d.ts

@@ -22,3 +22,25 @@ export declare const mouseScrollUpLines: (lines: number, lineHeight?: number) =>
  * @param lineHeight 行高（默认值为175像素）
  */
 export declare const mouseScrollDownLines: (lines: number, lineHeight?: number) => Promise<void>;
+/**
+ * 鼠标拖拽滑动到指定位置
+ * @param x1 起始水平方向偏移量（像素）
+ * @param y1 起始垂直方向偏移量（像素）
+ * @param x2 终止水平方向偏移量（像素）
+ * @param y2 终止垂直方向偏移量（像素）
+ */
+export declare const mouseSlide: (x1: number, y1: number, x2: number, y2: number) => Promise<void>;
+/**
+ * 鼠标水平拖拽滑动指定距离
+ * @param x 起始水平方向偏移量（像素）
+ * @param y 起始垂直方向偏移量（像素）
+ * @param distance 水平拖拽滑动距离（像素） 正数向右，负数向左
+ */
+export declare const mouseSlideX: (x: number, y: number, distance: number) => Promise<void>;
+/**
+ * 鼠标垂直拖拽滑动指定距离
+ * @param x 起始水平方向偏移量（像素）
+ * @param y 起始垂直方向偏移量（像素）
+ * @param distance 垂直拖拽滑动距离（像素） 正数向下，负数向上
+ */
+export declare const mouseSlideY: (x: number, y: number, distance: number) => Promise<void>;

package/dist/mouse.js

@@ -41,3 +41,37 @@ export const mouseScrollUpLines = (lines, lineHeight) => {
 export const mouseScrollDownLines = (lines, lineHeight) => {
     return mouseScrollDown(lines * (lineHeight ?? 175));
 };
+/**
+ * 鼠标拖拽滑动到指定位置
+ * @param x1 起始水平方向偏移量（像素）
+ * @param y1 起始垂直方向偏移量（像素）
+ * @param x2 终止水平方向偏移量（像素）
+ * @param y2 终止垂直方向偏移量（像素）
+ */
+export const mouseSlide = async (x1, y1, x2, y2) => {
+    moveMouseTo(x1, y1);
+    await sleep(50);
+    leftButtonDown();
+    await sleep(50);
+    moveMouseTo(x2, y2);
+    await sleep(50);
+    leftButtonUp();
+};
+/**
+ * 鼠标水平拖拽滑动指定距离
+ * @param x 起始水平方向偏移量（像素）
+ * @param y 起始垂直方向偏移量（像素）
+ * @param distance 水平拖拽滑动距离（像素） 正数向右，负数向左
+ */
+export const mouseSlideX = (x, y, distance) => {
+    return mouseSlide(x, y, x + distance, y);
+};
+/**
+ * 鼠标垂直拖拽滑动指定距离
+ * @param x 起始水平方向偏移量（像素）
+ * @param y 起始垂直方向偏移量（像素）
+ * @param distance 垂直拖拽滑动距离（像素） 正数向下，负数向上
+ */
+export const mouseSlideY = (x, y, distance) => {
+    return mouseSlide(x, y, x, y + distance);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/utils",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Utils for BetterGI JavaScript Development",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",