@bettergi/utils 0.1.19 → 0.1.21

package/README.md

@@ -59,6 +59,16 @@ const i3 = findImageBetweenCoordinates("assets/关闭.png", 960, 0, 1920, 1080);
 // 在指定方向上搜索图片，找不到返回 undefined
 const i4 = findImageInDirection("assets/关闭.png", "north-east");
 
+// 在列表视图中查找图片，并滚动列表视图直到找到目标图片 或 列表视图触底
+const i5 = await findImageWithinListView("assets/foo.png", {
+  x: 115,
+  y: 95,
+  w: 1157,
+  h: 906,
+  lineHeight: 175,
+  scrollLines: 4
+});
+
 // 在整个画面内搜索文本（不包含、忽略大小写），找不到返回 undefined
 const t1 = findText("购买");
 
@@ -70,6 +80,20 @@ const t3 = findTextBetweenCoordinates("确认", 960, 540, 1920, 1080);
 
 // 在指定方向上搜索文本（包含、忽略大小写），找不到返回 undefined
 const t4 = findTextInDirection("师傅", "east", { contains: true, ignoreCase: true });
+
+// 在列表视图中查找文本，并滚动列表视图直到找到目标文本 或 列表视图触底
+const t5 = await findTextWithinListView(
+  "小麦",
+  {
+    x: 120,
+    y: 95,
+    w: 1045,
+    h: 865,
+    lineHeight: 115,
+    scrollLines: 7
+  },
+  { contains: true }
+);
 ```
 
 ### 行为流程
@@ -102,22 +126,32 @@ await assertRegionDisappearing(findButton, "点击购买按钮超时", () => fin
 > 对常见鼠标操作的封装，如鼠标的平滑移动、鼠标滚轮滚动、鼠标拖拽等。
 
 ```ts
-// 鼠标从 (745, 610) 平滑自然地移动 (1920, 1080)
-await naturalMouseMove(745, 610, 1920, 1080);
+// 鼠标沿路径点移动并拖拽
+await mouseMoveAlongWaypoints(
+  [
+    { x: 100, y: 100 },
+    { x: 200, y: 200 },
+    { x: 300, y: 300 }
+  ],
+  { shouldDrag: true }
+);
 
 // 鼠标从 (745, 610) 拖拽到 (1280, 610)
 await mouseDrag(745, 610, 1280, 610);
 
+// 鼠标从 (745, 610) 平滑自然地移动 (1920, 1080)
+await naturalMouseMove(745, 610, 1920, 1080);
+
 // 鼠标滚轮向上滚动 175 像素
 await mouseScrollUp(175);
 
 // 鼠标滚轮向下滚动 175 像素
 await mouseScrollDown(175);
 
-// 鼠标滚轮向上滚动 99 行，行高 175（默认: 背包物品行高）
+// 鼠标滚轮向上滚动 99 行（默认: 175为背包物品行高）
 await mouseScrollUpLines(99);
 
-// 鼠标滚轮向下滚动 1 行，行高 115（自定义: 商店物品行高）
+// 鼠标滚轮向下滚动 1 行（自定义: 115为商店物品行高）
 await mouseScrollDownLines(1, 115);
 ```
 
@@ -177,12 +211,14 @@ tracker.complete(`任务完成`);
 
 ```ts
 // 发送 GET 请求获取响应体内容
-const body1 = await getForBody("https://example.com/", undefined, { "User-Agent": "BetterGI" });
-log.info(`GET 请求响应体内容${body1}`);
+const body1 = await getForBody("https://jsonplaceholder.typicode.com/todos/1");
 
 // 发送 POST 请求获取响应体内容
-const body2 = await postForBody("https://example.com/", undefined, { "User-Agent": "BetterGI" });
-log.info(`POST 请求响应体内容${body2}`);
+const body2 = await postForBody("https://jsonplaceholder.typicode.com/posts", {
+  title: "foo",
+  body: "bar",
+  userId: 1
+});
 ```
 
 ### 文件操作

package/dist/http.d.ts

@@ -2,24 +2,24 @@
  * 发送 HTTP 请求，获取响应体内容
  * @param method 请求方法
  * @param url 请求 URL
- * @param body 请求体
+ * @param body 请求体（UTF-8 编码）
  * @param headers 请求头
  * @returns 响应体内容
  */
-export declare const requestForBody: (method: Parameters<typeof http.request>[0], url: string, body?: string, headers?: Record<string, any>) => Promise<string>;
+export declare const requestForBody: (method: Parameters<typeof http.request>[0], url: string, body?: string | object, headers?: Record<string, any>) => Promise<string>;
 /**
  * 发送 HTTP GET 请求，获取响应体内容
  * @param url 请求 URL
- * @param body 请求体
+ * @param body 请求体（UTF-8 编码）
  * @param headers 请求头
  * @returns 响应体内容
  */
-export declare const getForBody: (url: string, body?: string, headers?: Record<string, any>) => Promise<string>;
+export declare const getForBody: (url: string, body?: string | object, headers?: Record<string, any>) => Promise<string>;
 /**
  * 发送 HTTP POST 请求，获取响应体内容
  * @param url 请求 URL
- * @param body 请求体
+ * @param body 请求体（UTF-8 编码）
  * @param headers 请求头
  * @returns 响应体内容
  */
-export declare const postForBody: (url: string, body?: string, headers?: Record<string, any>) => Promise<string>;
+export declare const postForBody: (url: string, body?: string | object, headers?: Record<string, any>) => Promise<string>;

package/dist/http.js

@@ -2,33 +2,37 @@
  * 发送 HTTP 请求，获取响应体内容
  * @param method 请求方法
  * @param url 请求 URL
- * @param body 请求体
+ * @param body 请求体（UTF-8 编码）
  * @param headers 请求头
  * @returns 响应体内容
  */
 export const requestForBody = async (method, url, body, headers) => {
-    const resp = await http.request(method, url, body ?? "null", headers ? JSON.stringify(headers) : "null");
+    if (body && typeof body === "object") {
+        body = JSON.stringify(body);
+        headers = { ...headers, "Content-Type": "application/json" };
+    }
+    const resp = await http.request(method, url, body ?? null, headers ? JSON.stringify(headers) : null);
     if (resp.status_code >= 200 && resp.status_code < 400) {
         return resp.body;
     }
     else {
-        throw new Error(`HTTP request failed with status ${resp.status_code}`);
+        throw new Error(`HTTP request failed with status ${resp.status_code}: ${resp.body}`);
     }
 };
 /**
  * 发送 HTTP GET 请求，获取响应体内容
  * @param url 请求 URL
- * @param body 请求体
+ * @param body 请求体（UTF-8 编码）
  * @param headers 请求头
  * @returns 响应体内容
  */
-export const getForBody = async (url, body, headers) => {
+export const getForBody = (url, body, headers) => {
     return requestForBody("GET", url, body, headers);
 };
 /**
  * 发送 HTTP POST 请求，获取响应体内容
  * @param url 请求 URL
- * @param body 请求体
+ * @param body 请求体（UTF-8 编码）
  * @param headers 请求头
  * @returns 响应体内容
  */

package/dist/mouse.js

@@ -72,9 +72,9 @@ export const naturalMouseMove = async (x1, y1, x2, y2, options) => {
     return mouseMoveAlongWaypoints(waypoints, options);
 };
 /** 使用回放脚本模拟滚动 */
-const simulateScroll = async (scrollAmountInClicks, times) => {
+const simulateScroll = async (wheelDelta, times) => {
     const script = {
-        macroEvents: Array(times).fill({ type: 6, mouseX: 0, mouseY: scrollAmountInClicks, time: 0 }),
+        macroEvents: Array(times).fill({ type: 6, mouseX: 0, mouseY: wheelDelta, time: 0 }),
         info: { name: "", description: "", x: 0, y: 0, width: 1920, height: 1080, recordDpi: 1.5 }
     };
     await keyMouseScript.run(JSON.stringify(script));
@@ -84,7 +84,7 @@ const simulateScroll = async (scrollAmountInClicks, times) => {
  * @param height 滚动高度
  * @param algorithm 自定义滚动算法函数，接收高度参数并返回滚动次数（默认算法为每18像素滚动一次）
  */
-export const mouseScrollUp = (height, algorithm = h => Math.floor(h / 18)) => {
+export const mouseScrollUp = (height, algorithm = h => Math.floor(h / 17.9795)) => {
     return simulateScroll(120, algorithm(height));
 };
 /**
@@ -92,7 +92,7 @@ export const mouseScrollUp = (height, algorithm = h => Math.floor(h / 18)) => {
  * @param height 滚动高度
  * @param algorithm 自定义滚动算法函数，接收高度参数并返回滚动次数（默认算法为每18像素滚动一次）
  */
-export const mouseScrollDown = (height, algorithm = h => Math.floor(h / 18)) => {
+export const mouseScrollDown = (height, algorithm = h => Math.floor(h / 17.9795)) => {
     return simulateScroll(-120, algorithm(height));
 };
 /**

package/dist/ocr.d.ts

@@ -9,14 +9,14 @@ export type ImageMat = ReturnType<typeof file.readImageMatSync>;
 export type MatchDirection = "north" /** 上半边 */ | "north-east" /** 右上四分之一 */ | "east" /** 右半边 */ | "south-east" /** 右下四分之一 */ | "south" /** 下半边 */ | "south-west" /** 左下四分之一 */ | "west" /** 左半边 */ | "north-west"; /** 左上四分之一 */
 /**
  * 在整个画面内搜索图片
- * @param image 图片路径 或 图片矩阵
+ * @param image 图片路径 或 图片Mat
  * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
 export declare const findImage: (image: string | ImageMat, config?: ROConfig) => Region | undefined;
 /**
  * 在指定区域内搜索图片
- * @param image 图片路径 或 图片矩阵
+ * @param image 图片路径 或 图片Mat
  * @param x 水平方向偏移量（像素）
  * @param y 垂直方向偏移量（像素）
  * @param w 宽度
@@ -27,7 +27,7 @@ export declare const findImage: (image: string | ImageMat, config?: ROConfig) =>
 export declare const findImageWithinBounds: (image: string | ImageMat, x: number, y: number, w: number, h: number, config?: ROConfig) => Region | undefined;
 /**
  * 在指定坐标范围内搜索图片
- * @param image 图片路径 或 图片矩阵
+ * @param image 图片路径 或 图片Mat
  * @param left 左边界偏移量（像素）
  * @param top 上边界偏移量（像素）
  * @param right 右边界偏移量（像素）
@@ -38,13 +38,13 @@ export declare const findImageWithinBounds: (image: string | ImageMat, x: number
 export declare const findImageBetweenCoordinates: (image: string | ImageMat, left: number, top: number, right: number, bottom: number, config?: ROConfig) => Region | undefined;
 /**
  * 在指定方向上搜索图片
- * @param image 图片路径 或 图片矩阵
+ * @param image 图片路径 或 图片Mat
  * @param direction 搜索方向
  * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
 export declare const findImageInDirection: (image: string | ImageMat, direction: MatchDirection, config?: ROConfig) => Region | undefined;
-/** 文本搜索选项 */
+/** 文本匹配选项 */
 export type TextMatchOptions = {
     /** 是否忽略大小写（默认: 是） */
     ignoreCase?: boolean;
@@ -107,6 +107,15 @@ export type ListView = {
     /** 纵向内边距 （默认: 10） */
     paddingY?: number;
 };
+/**
+ * 在列表视图中滚动搜索区域
+ * @param condition 查找条件
+ * @param listView 列表视图参数
+ * @param retryOptions 重试选项
+ * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：取上半部分）
+ * @returns 如果找到匹配的区域，则返回该区域，否则返回 undefined
+ */
+export declare const findWithinListView: (condition: (listViewRegion: ImageRegion) => Region | undefined, listView: ListView, retryOptions?: RetryOptions, sampling?: (listViewRegion: ImageRegion) => ImageRegion) => Promise<Region | undefined>;
 /**
  * 在列表视图中滚动搜索文本
  * @param text 待搜索文本
@@ -116,4 +125,13 @@ export type ListView = {
  * @param config 识别对象配置
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
-export declare const findTextWithinListView: (text: string, listView: ListView, matchOptions?: TextMatchOptions, retryOptions?: RetryOptions, config?: ROConfig) => Promise<Region | undefined>;
+export declare const findTextWithinListView: (text: string, listView: ListView, matchOptions?: TextMatchOptions, retryOptions?: RetryOptions, config?: ROConfig, sampling?: (listViewRegion: ImageRegion) => ImageRegion) => Promise<Region | undefined>;
+/**
+ * 在列表视图中查找图像
+ * @param image 图片路径 或 图片Mat
+ * @param listView 列表视图参数
+ * @param config 识别对象配置
+ * @param retryOptions 重试选项
+ * @returns 如果找到匹配的区域，则返回该区域，否则返回 undefined
+ */
+export declare const findImageWithinListView: (image: string | ImageMat, listView: ListView, config?: ROConfig, retryOptions?: RetryOptions, sampling?: (listViewRegion: ImageRegion) => ImageRegion) => Promise<Region | undefined>;

package/dist/ocr.js

@@ -15,7 +15,7 @@ const directionToBounds = (direction) => {
 };
 /**
  * 在整个画面内搜索图片
- * @param image 图片路径 或 图片矩阵
+ * @param image 图片路径 或 图片Mat
  * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
@@ -39,7 +39,7 @@ export const findImage = (image, config = {}) => {
 };
 /**
  * 在指定区域内搜索图片
- * @param image 图片路径 或 图片矩阵
+ * @param image 图片路径 或 图片Mat
  * @param x 水平方向偏移量（像素）
  * @param y 垂直方向偏移量（像素）
  * @param w 宽度
@@ -67,7 +67,7 @@ export const findImageWithinBounds = (image, x, y, w, h, config = {}) => {
 };
 /**
  * 在指定坐标范围内搜索图片
- * @param image 图片路径 或 图片矩阵
+ * @param image 图片路径 或 图片Mat
  * @param left 左边界偏移量（像素）
  * @param top 上边界偏移量（像素）
  * @param right 右边界偏移量（像素）
@@ -80,7 +80,7 @@ export const findImageBetweenCoordinates = (image, left, top, right, bottom, con
 };
 /**
  * 在指定方向上搜索图片
- * @param image 图片路径 或 图片矩阵
+ * @param image 图片路径 或 图片Mat
  * @param direction 搜索方向
  * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
@@ -89,7 +89,14 @@ export const findImageInDirection = (image, direction, config = {}) => {
     const { x, y, w, h } = directionToBounds(direction);
     return findImageWithinBounds(image, x, y, w, h, config);
 };
-const findFirst = (ir, ro, predicate) => {
+/**
+ * 在图像区域内查找第一个符合条件的识别区域
+ * @param ir 图像区域
+ * @param ro 识别对象
+ * @param predicate 筛选条件
+ * @returns 第一个符合条件的识别区域，未找到则返回 undefined
+ */
+const findFirstRegion = (ir, ro, predicate) => {
     const candidates = ir.findMulti(ro);
     for (let i = 0; i < candidates.count; i++) {
         if (predicate(candidates[i]))
@@ -97,6 +104,19 @@ const findFirst = (ir, ro, predicate) => {
     }
     return undefined;
 };
+/**
+ * 文本匹配
+ * @param text 待匹配文本
+ * @param searchText 待搜索文本
+ * @param options 搜索选项
+ * @returns 是否匹配
+ */
+const textMatch = (text, searchText, options) => {
+    const { ignoreCase = true, contains = false } = options || {};
+    text = ignoreCase ? text.toLowerCase() : text;
+    searchText = ignoreCase ? searchText.toLowerCase() : searchText;
+    return contains ? text.includes(searchText) : text === searchText;
+};
 /**
  * 在整个画面内搜索文本
  * @param text 待搜索文本
@@ -105,18 +125,14 @@ const findFirst = (ir, ro, predicate) => {
  * @returns 如果找到匹配的文本区域，则返回该区域
  */
 export const findText = (text, options, config = {}) => {
-    const { ignoreCase = true, contains = false } = options || {};
-    const searchText = ignoreCase ? text.toLowerCase() : text;
     const ir = captureGameRegion();
     try {
         const ro = RecognitionObject.ocrThis;
         if (Object.keys(config).length > 0) {
             Object.assign(ro, config) && ro.initTemplate();
         }
-        return findFirst(ir, ro, region => {
-            const itemText = ignoreCase ? region.text.toLowerCase() : region.text;
-            const isMatch = contains ? itemText.includes(searchText) : itemText === searchText;
-            return isMatch && region.isExist();
+        return findFirstRegion(ir, ro, region => {
+            return region.isExist() && textMatch(region.text, text, options);
         });
     }
     catch (err) {
@@ -138,18 +154,14 @@ export const findText = (text, options, config = {}) => {
  * @returns 如果找到匹配的文本区域，则返回该区域
  */
 export const findTextWithinBounds = (text, x, y, w, h, options, config = {}) => {
-    const { ignoreCase = true, contains = false } = options || {};
-    const searchText = ignoreCase ? text.toLowerCase() : text;
     const ir = captureGameRegion();
     try {
         const ro = RecognitionObject.ocr(x, y, w, h);
         if (Object.keys(config).length > 0) {
             Object.assign(ro, config) && ro.initTemplate();
         }
-        return findFirst(ir, ro, region => {
-            const itemText = ignoreCase ? region.text.toLowerCase() : region.text;
-            const isMatch = contains ? itemText.includes(searchText) : itemText === searchText;
-            return isMatch && region.isExist();
+        return findFirstRegion(ir, ro, region => {
+            return region.isExist() && textMatch(region.text, text, options);
         });
     }
     catch (err) {
@@ -186,40 +198,75 @@ export const findTextInDirection = (text, direction, options, config = {}) => {
     return findTextWithinBounds(text, x, y, w, h, options, config);
 };
 /**
- * 在列表视图中滚动搜索文本
- * @param text 待搜索文本
+ * 在列表视图中滚动搜索区域
+ * @param condition 查找条件
  * @param listView 列表视图参数
- * @param matchOptions 搜索选项
  * @param retryOptions 重试选项
- * @param config 识别对象配置
- * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：取上半部分）
+ * @returns 如果找到匹配的区域，则返回该区域，否则返回 undefined
  */
-export const findTextWithinListView = async (text, listView, matchOptions, retryOptions, config = {}) => {
+export const findWithinListView = async (condition, listView, retryOptions, sampling) => {
     const { x, y, w, h, lineHeight, scrollLines = 1, paddingX = 10, paddingY = 10 } = listView;
-    const { maxAttempts = 30, retryInterval = 1000 } = retryOptions || {};
-    const findTargetText = () => findTextWithinBounds(text, x, y, w, h, matchOptions, config);
-    let lastTextRegion;
+    const { maxAttempts = 99, retryInterval = 1000 } = retryOptions || {};
+    sampling = sampling || (r => r.deriveCrop(0, 0, r.width, Math.floor(r.height / 2)));
+    const captureListViewRegion = () => captureGameRegion().deriveCrop(x, y, w, h);
+    let _lvr;
     const isReachedBottom = () => {
-        const textRegion = findFirst(captureGameRegion(), RecognitionObject.ocr(x, y, w, h), region => {
-            return region.isExist() && region.text.trim().length > 0;
-        });
-        if (textRegion) {
-            if (lastTextRegion?.text === textRegion.text &&
-                Math.abs(textRegion.y - lastTextRegion.y) < lineHeight) {
+        const region = sampling(captureListViewRegion());
+        if (region?.isExist()) {
+            if (_lvr?.find(RecognitionObject.templateMatch(region.srcMat))) {
                 return true;
             }
             else {
-                lastTextRegion = textRegion;
+                _lvr = region;
                 return false;
             }
         }
-        // 异常情况: 找不到任何文本
-        return true;
+        return true; // 异常情况: 无法获取列表视图截图
     };
-    const isTextFoundOrBottomReached = await waitForAction(() => findTargetText() != undefined || isReachedBottom(), async () => {
+    const isFoundOrReachedBottom = await waitForAction(() => condition(captureListViewRegion())?.isExist() || isReachedBottom(), async () => {
         moveMouseTo(x + w - paddingX, y + paddingY); // 移动到滚动条附近
         await sleep(50);
         await mouseScrollDownLines(scrollLines, lineHeight); // 滚动指定行数
     }, { maxAttempts, retryInterval });
-    return isTextFoundOrBottomReached ? findTargetText() : undefined;
+    return isFoundOrReachedBottom ? condition(captureListViewRegion()) : undefined;
+};
+/**
+ * 在列表视图中滚动搜索文本
+ * @param text 待搜索文本
+ * @param listView 列表视图参数
+ * @param matchOptions 搜索选项
+ * @param retryOptions 重试选项
+ * @param config 识别对象配置
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ */
+export const findTextWithinListView = async (text, listView, matchOptions, retryOptions, config = {}, sampling) => {
+    const ro = RecognitionObject.ocrThis;
+    if (Object.keys(config).length > 0) {
+        Object.assign(ro, config) && ro.initTemplate();
+    }
+    return findWithinListView(lvr => {
+        return findFirstRegion(lvr, ro, region => {
+            return region.isExist() && textMatch(region.text, text, matchOptions);
+        });
+    }, listView, retryOptions, sampling);
+};
+/**
+ * 在列表视图中查找图像
+ * @param image 图片路径 或 图片Mat
+ * @param listView 列表视图参数
+ * @param config 识别对象配置
+ * @param retryOptions 重试选项
+ * @returns 如果找到匹配的区域，则返回该区域，否则返回 undefined
+ */
+export const findImageWithinListView = async (image, listView, config = {}, retryOptions, sampling) => {
+    const mat = typeof image === "string" ? file.readImageMatSync(image) : image;
+    const ro = RecognitionObject.templateMatch(mat);
+    if (Object.keys(config).length > 0) {
+        Object.assign(ro, config) && ro.initTemplate();
+    }
+    return findWithinListView(ir => {
+        const region = ir.find(ro);
+        return region.isExist() ? region : undefined;
+    }, listView, retryOptions, sampling);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/utils",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "开发 BetterGI 脚本常用工具集",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",
@@ -33,8 +33,8 @@
     "build": "rimraf dist && tsc"
   },
   "devDependencies": {
-    "@bettergi/types": "workspace:latest",
-    "rimraf": "^6.1.0",
+    "@bettergi/types": "workspace:^",
+    "rimraf": "^6.1.2",
     "typescript": "^5.9.3"
   }
 }