@bettergi/utils 0.1.10 → 0.1.12

package/README.md

@@ -47,23 +47,29 @@ await navigateToTab(() => {
 > 对 RecognitionObject 代码的封装，对于简单的找图、找字操作，不再需要编写复杂的代码。
 
 ```ts
-// 在整个画面内搜索图片，相似度0.8（默认），找不到返回 undefined
-const i1 = findImage("assets/关闭.png");
+// 在整个画面内搜索图片，找不到返回 undefined
+const i1 = findImage("assets/关闭.png", { use3Channels: true }); // 匹配颜色
 
-// 在指定方向上搜索图片，相似度0.9，找不到返回 undefined
-const i2 = findImageInDirection("assets/关闭.png", "north-east", 0.9);
+// 在指定区域内搜索图片，找不到返回 undefined
+const i2 = findImageWithinBounds("assets/关闭.png", 960, 0, 960, 1080);
 
-// 在指定区域内搜索图片，相似度0.8（默认），找不到返回 undefined
-const i3 = findImageWithinBounds("assets/关闭.png", 960, 0, 960, 1080);
+// 在指定坐标范围内搜索图片，找不到返回 undefined
+const i3 = findImageBetweenCoordinates("assets/关闭.png", 960, 0, 1920, 1080);
+
+// 在指定方向上搜索图片，找不到返回 undefined
+const i4 = findImageInDirection("assets/关闭.png", "north-east");
 
 // 在整个画面内搜索文本（不包含、忽略大小写），找不到返回 undefined
 const t1 = findText("购买");
 
-// 在指定方向上搜索文本（包含、忽略大小写），找不到返回 undefined
-const t2 = findTextInDirection("师傅", "east", { contains: true, ignoreCase: true });
-
 // 在指定区域内搜索文本（不包含、忽略大小写），找不到返回 undefined
-const t3 = findTextWithinBounds("确认", 960, 540, 960, 540);
+const t2 = findTextWithinBounds("确认", 960, 540, 960, 540);
+
+// 在指定坐标范围内搜索文本（不包含、忽略大小写），找不到返回 undefined
+const t3 = findTextBetweenCoordinates("确认", 960, 540, 1920, 1080);
+
+// 在指定方向上搜索文本（包含、忽略大小写），找不到返回 undefined
+const t4 = findTextInDirection("师傅", "east", { contains: true, ignoreCase: true });
 ```
 
 ### 行为流程
@@ -119,7 +125,7 @@ await mouseScrollUpLines(99);
 await mouseScrollDownLines(1, 115);
 ```
 
-### 数据存储
+### 状态管理和持久化
 
 > 对象数据持久化，通过 Proxy 实现自动存储。从而可以无感知地读取/更新数据，而无需考虑如何持久化。
 

package/dist/game.d.ts

@@ -28,7 +28,7 @@ export declare const openMenu: (name: "\u62CD\u7167" | "\u516C\u544A" | "\u90AE\
  * @param listView 菜单页面视图参数
  */
 export declare const openMenuPage: (name: "\u5546\u57CE" | "\u961F\u4F0D\u914D\u7F6E" | "\u597D\u53CB" | "\u6210\u5C31" | "\u56FE\u9274" | "\u89D2\u8272\u56FE\u9274" | "\u89D2\u8272" | "\u63D0\u5347\u6307\u5357" | "\u80CC\u5305" | "\u4EFB\u52A1" | "\u5730\u56FE" | "\u6D3B\u52A8" | "\u5192\u9669\u4E4B\u8BC1" | "\u7948\u613F" | "\u7EAA\u884C" | "\u591A\u4EBA\u6E38\u620F" | "\u5343\u661F\u5546\u57CE" | "\u4EBA\u6C14\u5947\u57DF" | "\u5947\u57DF\u6536\u85CF" | "\u6211\u7684\u5947\u57DF" | "\u5927\u5385" | "\u88C5\u626E\u642D\u914D" | "\u9882\u613F" | "\u7EAA\u6E38" | (string & {}), listView?: ListView) => Promise<void>;
-type ClockOptions = {
+export type ClockOptions = {
     /** 时钟中心X坐标 */
     centerX?: number;
     /** 时钟中心Y坐标 */
@@ -54,7 +54,7 @@ export declare const setTimeTo: (hour: number, minute: number, options?: ClockOp
  */
 export declare const setTime: (period: "night" | "morning" | "noon" | "evening", options?: ClockOptions) => Promise<void>;
 /** tab 翻页配置 */
-type TabNavigationOptions = {
+export type TabNavigationOptions = {
     /** 标签页图标宽度（默认：96） */
     tabIconWidth?: number;
     /** 翻页按钮垂直偏移（默认：540） */
@@ -78,4 +78,3 @@ type TabNavigationOptions = {
  *          - false 达到最大重试次数
  */
 export declare const navigateToTab: (condition: () => boolean, options?: TabNavigationOptions) => Promise<boolean>;
-export {};

package/dist/mouse.d.ts

@@ -1,6 +1,8 @@
-type MouseWaypointsOptions = {
+export type MouseWaypointsOptions = {
     /** 是否按住鼠标左键拖动 */
     shouldDrag?: boolean;
+    /** 移动延时（毫秒） */
+    delay?: number;
     /** 超时时间（毫秒，默认: 不超时） */
     timeout?: number;
 };
@@ -22,7 +24,7 @@ export declare const mouseMoveAlongWaypoints: (waypoints: {
  * @param y2 终止垂直方向偏移量（像素）
  */
 export declare const mouseDrag: (x1: number, y1: number, x2: number, y2: number) => Promise<boolean>;
-type NaturalMouseMoveOptions = {
+export type NaturalMouseMoveOptions = {
     /** 移动持续时间（毫秒，默认: 800） */
     duration: number;
     /** 摆动幅度（默认: 30） */
@@ -71,4 +73,3 @@ export declare const mouseScrollUpLines: (lines: number, lineHeight?: number) =>
  * @param lineHeight 行高（默认值为175像素）
  */
 export declare const mouseScrollDownLines: (lines: number, lineHeight?: number) => Promise<void>;
-export {};

package/dist/mouse.js

@@ -4,7 +4,7 @@
  * @param options 鼠标移动选项
  */
 export const mouseMoveAlongWaypoints = async (waypoints, options) => {
-    const { shouldDrag = false, timeout = 0 } = options || {};
+    const { shouldDrag = false, delay = 50, timeout = 0 } = options || {};
     try {
         const startTime = Date.now();
         for (let i = 0; i < waypoints.length; i++) {
@@ -13,9 +13,9 @@ export const mouseMoveAlongWaypoints = async (waypoints, options) => {
                 leftButtonDown();
             moveMouseTo(Math.trunc(waypoints[i].x), Math.trunc(waypoints[i].y));
             // 等待指定延迟
-            const delay = Math.trunc(waypoints[i].delay || 50);
-            if (delay > 0)
-                await sleep(delay);
+            const duration = Math.trunc(waypoints[i].delay || delay);
+            if (duration > 0)
+                await sleep(duration);
             // 超时检查
             if (timeout > 0 && Date.now() - startTime > timeout)
                 return false;

package/dist/ocr.d.ts

@@ -1,12 +1,18 @@
 import { RetryOptions } from "./workflow";
-type MatchDirection = "north" /** 上半边 */ | "north-east" /** 右上四分之一 */ | "east" /** 右半边 */ | "south-east" /** 右下四分之一 */ | "south" /** 下半边 */ | "south-west" /** 左下四分之一 */ | "west" /** 左半边 */ | "north-west"; /** 左上四分之一 */
+/** 识别对象实例 */
+export type ROInstance = InstanceType<typeof RecognitionObject>;
+/** 识别对象配置 */
+export type ROConfig = Partial<{
+    [K in keyof ROInstance as ROInstance[K] extends Function ? never : K]: ROInstance[K];
+}>;
+export type MatchDirection = "north" /** 上半边 */ | "north-east" /** 右上四分之一 */ | "east" /** 右半边 */ | "south-east" /** 右下四分之一 */ | "south" /** 下半边 */ | "south-west" /** 左下四分之一 */ | "west" /** 左半边 */ | "north-west"; /** 左上四分之一 */
 /**
  * 在整个画面内搜索图片
  * @param path 图片路径
- * @param similarity 相似度阈值（默认: 0.8）
+ * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
-export declare const findImage: (path: string, similarity?: number) => Region | undefined;
+export declare const findImage: (path: string, config?: ROConfig) => Region | undefined;
 /**
  * 在指定区域内搜索图片
  * @param path 图片路径
@@ -14,19 +20,31 @@ export declare const findImage: (path: string, similarity?: number) => Region |
  * @param y 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
- * @param similarity 相似度阈值（默认: 0.8）
+ * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
-export declare const findImageWithinBounds: (path: string, x: number, y: number, w: number, h: number, similarity?: number) => Region | undefined;
+export declare const findImageWithinBounds: (path: string, x: number, y: number, w: number, h: number, config?: ROConfig) => Region | undefined;
+/**
+ * 在指定坐标范围内搜索图片
+ * @param path 图片路径
+ * @param left 左边界偏移量（像素）
+ * @param top 上边界偏移量（像素）
+ * @param right 右边界偏移量（像素）
+ * @param bottom 下边界偏移量（像素）
+ * @param config 识别对象配置
+ * @returns 如果找到匹配的图片区域，则返回该区域
+ */
+export declare const findImageBetweenCoordinates: (path: string, left: number, top: number, right: number, bottom: number, config?: ROConfig) => Region | undefined;
 /**
  * 在指定方向上搜索图片
  * @param path 图片路径
  * @param direction 搜索方向
+ * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
-export declare const findImageInDirection: (path: string, direction: MatchDirection, similarity?: number) => Region | undefined;
+export declare const findImageInDirection: (path: string, direction: MatchDirection, config?: ROConfig) => Region | undefined;
 /** 文本搜索选项 */
-type TextMatchOptions = {
+export type TextMatchOptions = {
     /** 是否忽略大小写（默认: 是） */
     ignoreCase?: boolean;
     /** 是否非完全匹配（默认: 否） */
@@ -36,9 +54,10 @@ type TextMatchOptions = {
  * 在整个画面内搜索文本
  * @param text 待搜索文本
  * @param options 搜索选项
+ * @param config 识别对象配置
  * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export declare const findText: (text: string, options?: TextMatchOptions) => Region | undefined;
+export declare const findText: (text: string, options?: TextMatchOptions, config?: ROConfig) => Region | undefined;
 /**
  * 在指定区域内搜索文本
  * @param text 待搜索文本
@@ -47,17 +66,31 @@ export declare const findText: (text: string, options?: TextMatchOptions) => Reg
  * @param w 宽度
  * @param h 高度
  * @param options 搜索选项
+ * @param config 识别对象配置
+ * @returns 如果找到匹配的文本区域，则返回该区域
+ */
+export declare const findTextWithinBounds: (text: string, x: number, y: number, w: number, h: number, options?: TextMatchOptions, config?: ROConfig) => Region | undefined;
+/**
+ * 在指定坐标范围内搜索文本
+ * @param text 待搜索文本
+ * @param left 左边界偏移量（像素）
+ * @param top 上边界偏移量（像素）
+ * @param right 右边界偏移量（像素）
+ * @param bottom 下边界偏移量（像素）
+ * @param options 搜索选项
+ * @param config 识别对象配置
  * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export declare const findTextWithinBounds: (text: string, x: number, y: number, w: number, h: number, options?: TextMatchOptions) => Region | undefined;
+export declare const findTextBetweenCoordinates: (text: string, left: number, top: number, right: number, bottom: number, options?: TextMatchOptions, config?: ROConfig) => Region | undefined;
 /**
  * 在指定方向上搜索文本
  * @param text 待搜索文本
  * @param direction 搜索方向
  * @param options 搜索选项
+ * @param config 识别对象配置
  * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export declare const findTextInDirection: (text: string, direction: MatchDirection, options?: TextMatchOptions) => Region | undefined;
+export declare const findTextInDirection: (text: string, direction: MatchDirection, options?: TextMatchOptions, config?: ROConfig) => Region | undefined;
 /** 列表视图参数 */
 export type ListView = {
     x: number;
@@ -78,8 +111,8 @@ export type ListView = {
  * @param text 待搜索文本
  * @param listView 列表视图参数
  * @param matchOptions 搜索选项
- * @param timeout 搜索超时
+ * @param retryOptions 重试选项
+ * @param config 识别对象配置
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
-export declare const findTextWithinListView: (text: string, listView: ListView, matchOptions?: TextMatchOptions, retryOptions?: RetryOptions) => Promise<Region | undefined>;
-export {};
+export declare const findTextWithinListView: (text: string, listView: ListView, matchOptions?: TextMatchOptions, retryOptions?: RetryOptions, config?: ROConfig) => Promise<Region | undefined>;

package/dist/ocr.js

@@ -24,14 +24,14 @@ const directionToBounds = (direction) => {
 /**
  * 在整个画面内搜索图片
  * @param path 图片路径
- * @param similarity 相似度阈值（默认: 0.8）
+ * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
-export const findImage = (path, similarity = 0.8) => {
+export const findImage = (path, config = {}) => {
     const ir = captureGameRegion();
     try {
         const ro = RecognitionObject.templateMatch(file.readImageMatSync(path));
-        ro.threshold = similarity;
+        Object.assign(ro, config);
         return findFirst(ir, ro, region => region.isExist());
     }
     catch (err) {
@@ -48,14 +48,14 @@ export const findImage = (path, similarity = 0.8) => {
  * @param y 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
- * @param similarity 相似度阈值（默认: 0.8）
+ * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
-export const findImageWithinBounds = (path, x, y, w, h, similarity = 0.8) => {
+export const findImageWithinBounds = (path, x, y, w, h, config = {}) => {
     const ir = captureGameRegion();
     try {
         const ro = RecognitionObject.templateMatch(file.readImageMatSync(path), x, y, w, h);
-        ro.threshold = similarity;
+        Object.assign(ro, config);
         return findFirst(ir, ro, region => region.isExist());
     }
     catch (err) {
@@ -65,28 +65,44 @@ export const findImageWithinBounds = (path, x, y, w, h, similarity = 0.8) => {
         ir.dispose();
     }
 };
+/**
+ * 在指定坐标范围内搜索图片
+ * @param path 图片路径
+ * @param left 左边界偏移量（像素）
+ * @param top 上边界偏移量（像素）
+ * @param right 右边界偏移量（像素）
+ * @param bottom 下边界偏移量（像素）
+ * @param config 识别对象配置
+ * @returns 如果找到匹配的图片区域，则返回该区域
+ */
+export const findImageBetweenCoordinates = (path, left, top, right, bottom, config = {}) => {
+    return findImageWithinBounds(path, left, top, right - left, bottom - top, config);
+};
 /**
  * 在指定方向上搜索图片
  * @param path 图片路径
  * @param direction 搜索方向
+ * @param config 识别对象配置
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
-export const findImageInDirection = (path, direction, similarity = 0.8) => {
+export const findImageInDirection = (path, direction, config = {}) => {
     const { x, y, w, h } = directionToBounds(direction);
-    return findImageWithinBounds(path, x, y, w, h, similarity);
+    return findImageWithinBounds(path, x, y, w, h, config);
 };
 /**
  * 在整个画面内搜索文本
  * @param text 待搜索文本
  * @param options 搜索选项
+ * @param config 识别对象配置
  * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export const findText = (text, options) => {
+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;
+        Object.assign(ro, config);
         return findFirst(ir, ro, region => {
             const itemText = ignoreCase ? region.text.toLowerCase() : region.text;
             const isMatch = contains ? itemText.includes(searchText) : itemText === searchText;
@@ -108,14 +124,16 @@ export const findText = (text, options) => {
  * @param w 宽度
  * @param h 高度
  * @param options 搜索选项
+ * @param config 识别对象配置
  * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export const findTextWithinBounds = (text, x, y, w, h, options) => {
+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);
+        Object.assign(ro, config);
         return findFirst(ir, ro, region => {
             const itemText = ignoreCase ? region.text.toLowerCase() : region.text;
             const isMatch = contains ? itemText.includes(searchText) : itemText === searchText;
@@ -129,29 +147,45 @@ export const findTextWithinBounds = (text, x, y, w, h, options) => {
         ir.dispose();
     }
 };
+/**
+ * 在指定坐标范围内搜索文本
+ * @param text 待搜索文本
+ * @param left 左边界偏移量（像素）
+ * @param top 上边界偏移量（像素）
+ * @param right 右边界偏移量（像素）
+ * @param bottom 下边界偏移量（像素）
+ * @param options 搜索选项
+ * @param config 识别对象配置
+ * @returns 如果找到匹配的文本区域，则返回该区域
+ */
+export const findTextBetweenCoordinates = (text, left, top, right, bottom, options, config = {}) => {
+    return findTextWithinBounds(text, left, top, right - left, bottom - top, options, config);
+};
 /**
  * 在指定方向上搜索文本
  * @param text 待搜索文本
  * @param direction 搜索方向
  * @param options 搜索选项
+ * @param config 识别对象配置
  * @returns 如果找到匹配的文本区域，则返回该区域
  */
-export const findTextInDirection = (text, direction, options) => {
+export const findTextInDirection = (text, direction, options, config = {}) => {
     const { x, y, w, h } = directionToBounds(direction);
-    return findTextWithinBounds(text, x, y, w, h, options);
+    return findTextWithinBounds(text, x, y, w, h, options, config);
 };
 /**
  * 在列表视图中滚动搜索文本
  * @param text 待搜索文本
  * @param listView 列表视图参数
  * @param matchOptions 搜索选项
- * @param timeout 搜索超时
+ * @param retryOptions 重试选项
+ * @param config 识别对象配置
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
-export const findTextWithinListView = async (text, listView, matchOptions, retryOptions) => {
+export const findTextWithinListView = async (text, listView, matchOptions, retryOptions, config = {}) => {
     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);
+    const findTargetText = () => findTextWithinBounds(text, x, y, w, h, matchOptions, config);
     let lastTextRegion;
     const isReachedBottom = () => {
         const textRegion = findFirst(captureGameRegion(), RecognitionObject.ocr(x, y, w, h), region => {
@@ -172,6 +206,7 @@ export const findTextWithinListView = async (text, listView, matchOptions, retry
     };
     const isTextFoundOrBottomReached = await waitForAction(() => findTargetText() != undefined || isReachedBottom(), async () => {
         moveMouseTo(x + w - paddingX, y + paddingY); // 移动到滚动条附近
+        await sleep(50);
         await mouseScrollDownLines(scrollLines, lineHeight); // 滚动指定行数
     }, { maxAttempts, retryInterval });
     return isTextFoundOrBottomReached ? findTargetText() : undefined;

package/dist/workflow.d.ts

@@ -1,4 +1,5 @@
 export type Action = () => Promise<void> | void;
+/** 重试选项 */
 export type RetryOptions = {
     /** 重试次数（默认: 5） */
     maxAttempts?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/utils",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "开发 BetterGI 脚本常用工具集",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",