@bettergi/utils 0.1.21 → 0.1.23

package/README.md

@@ -51,7 +51,7 @@ await navigateToTab(() => {
 const i1 = findImage("assets/关闭.png", { use3Channels: true }); // 匹配颜色
 
 // 在指定区域内搜索图片，找不到返回 undefined
-const i2 = findImageWithinBounds("assets/关闭.png", 960, 0, 960, 1080);
+const i2 = findImageWithinBounds("assets/关闭.png", 960, 0, 960, 1080, { threshold: 0.75 }); // 阈值0.75
 
 // 在指定坐标范围内搜索图片，找不到返回 undefined
 const i3 = findImageBetweenCoordinates("assets/关闭.png", 960, 0, 1920, 1080);
@@ -157,7 +157,7 @@ await mouseScrollDownLines(1, 115);
 
 ### 状态管理和持久化
 
-> 基于深度 Proxy 实现的对象数据持久化，能够在数据被修改时自动同步至文件。使开发其能够像操作普通对象一样进行数据读写，而无需关心底层的持久化细节。
+> 基于深度 Proxy 实现的对象数据持久化，能够在数据被修改时自动同步至文件。使开发者能够像操作普通对象一样进行数据读写，而无需关心底层的持久化细节。
 
 ```ts
 // 创建/读取存储对象，保存到存储文件 store/my-data.json 中

package/dist/game.d.ts

@@ -1,4 +1,4 @@
-import { ListView } from "./ocr";
+import { type ListView } from "./ocr";
 /**
  * 临时设置游戏分辨率和DPI缩放比例，执行指定动作后恢复
  * 适用于使用了鼠标移动的操作，保证在不同的分辨率和DPI下都能正确地复现鼠标操作

package/dist/game.js

@@ -1,6 +1,6 @@
 import { assertRegionAppearing, assertRegionDisappearing } from "./asserts";
 import { mouseMoveAlongWaypoints } from "./mouse";
-import { findTextInDirection, findTextWithinBounds, findTextWithinListView } from "./ocr";
+import { findTextWithinBounds, findTextWithinListView } from "./ocr";
 /**
  * 临时设置游戏分辨率和DPI缩放比例，执行指定动作后恢复
  * 适用于使用了鼠标移动的操作，保证在不同的分辨率和DPI下都能正确地复现鼠标操作
@@ -10,13 +10,13 @@ import { findTextInDirection, findTextWithinBounds, findTextWithinListView } fro
  * @param action 执行动作
  */
 export const withGameMetrics = async (w, h, dpi, action) => {
-    const [_w, _h, _dpi] = globalThis["getGameMetrics"] ? getGameMetrics() : [];
+    const [_w, _h, _dpi] = getGameMetrics();
     try {
         setGameMetrics(w, h, dpi);
         return await action();
     }
     finally {
-        globalThis["getGameMetrics"] && setGameMetrics(_w, _h, _dpi);
+        setGameMetrics(_w, _h, _dpi);
     }
 };
 /**
@@ -71,14 +71,14 @@ export const openMenuPage = async (name, listView) => {
     // 1.打开派蒙菜单
     await openPaimonMenu();
     // 2.搜索菜单页面按钮
+    const { x = 95, y = 330, w = 670, h = 730, lineHeight = 142 } = listView || {};
     const button = await withGameMetrics(1920, 1080, 1.5, async () => {
-        const { x = 95, y = 330, w = 670, h = 730, lineHeight = 142 } = listView || {};
-        return await findTextWithinListView(name, { x, y, w, h, lineHeight, scrollLines: 2 });
+        return await findTextWithinListView(name, { x, y, w, h, lineHeight, scrollLines: 5 });
     });
     if (!button)
         throw new Error(`搜索菜单页面 ${name} 失败`);
     // 3.点击打开菜单页面
-    await assertRegionDisappearing(() => findTextWithinBounds(name, button.x, button.y, button.width, button.height), `打开菜单页面 ${name} 超时`, () => {
+    await assertRegionDisappearing(() => findTextWithinBounds(name, x, y, w, h), `打开菜单页面 ${name} 超时`, () => {
         button.click();
     });
 };
@@ -108,8 +108,8 @@ export const setTimeTo = async (hour, minute, options) => {
         // 拨动指针
         await mouseMoveAlongWaypoints(waypoints, { shouldDrag: true });
         // 点击确认按钮，等待调整结束
-        await assertRegionAppearing(() => findTextInDirection("时间少于", "south-east", { contains: true }), "调整时间超时", () => {
-            findTextInDirection("确认", "south-east")?.click();
+        await assertRegionAppearing(() => findTextWithinBounds("时间少于", 960, 540, 960, 540, { contains: true }), "调整时间超时", () => {
+            findTextWithinBounds("确认", 960, 540, 960, 540)?.click();
         }, { maxAttempts: 20, retryInterval: 1000 });
     });
     // 4.返回主界面

package/dist/ocr.d.ts

@@ -1,4 +1,4 @@
-import { RetryOptions } from "./workflow";
+import { type RetryOptions } from "./workflow";
 /** 识别对象实例 */
 export type ROInstance = InstanceType<typeof RecognitionObject>;
 /** 识别对象配置 */
@@ -11,7 +11,7 @@ export type MatchDirection = "north" /** 上半边 */ | "north-east" /** 右上
  * 在整个画面内搜索图片
  * @param image 图片路径 或 图片Mat
  * @param config 识别对象配置
- * @returns 如果找到匹配的图片区域，则返回该区域
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export declare const findImage: (image: string | ImageMat, config?: ROConfig) => Region | undefined;
 /**
@@ -22,7 +22,7 @@ export declare const findImage: (image: string | ImageMat, config?: ROConfig) =>
  * @param w 宽度
  * @param h 高度
  * @param config 识别对象配置
- * @returns 如果找到匹配的图片区域，则返回该区域
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export declare const findImageWithinBounds: (image: string | ImageMat, x: number, y: number, w: number, h: number, config?: ROConfig) => Region | undefined;
 /**
@@ -33,7 +33,7 @@ export declare const findImageWithinBounds: (image: string | ImageMat, x: number
  * @param right 右边界偏移量（像素）
  * @param bottom 下边界偏移量（像素）
  * @param config 识别对象配置
- * @returns 如果找到匹配的图片区域，则返回该区域
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export declare const findImageBetweenCoordinates: (image: string | ImageMat, left: number, top: number, right: number, bottom: number, config?: ROConfig) => Region | undefined;
 /**
@@ -41,7 +41,7 @@ export declare const findImageBetweenCoordinates: (image: string | ImageMat, lef
  * @param image 图片路径 或 图片Mat
  * @param direction 搜索方向
  * @param config 识别对象配置
- * @returns 如果找到匹配的图片区域，则返回该区域
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export declare const findImageInDirection: (image: string | ImageMat, direction: MatchDirection, config?: ROConfig) => Region | undefined;
 /** 文本匹配选项 */
@@ -56,7 +56,7 @@ export type TextMatchOptions = {
  * @param text 待搜索文本
  * @param options 搜索选项
  * @param config 识别对象配置
- * @returns 如果找到匹配的文本区域，则返回该区域
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export declare const findText: (text: string, options?: TextMatchOptions, config?: ROConfig) => Region | undefined;
 /**
@@ -68,7 +68,7 @@ export declare const findText: (text: string, options?: TextMatchOptions, config
  * @param h 高度
  * @param options 搜索选项
  * @param config 识别对象配置
- * @returns 如果找到匹配的文本区域，则返回该区域
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export declare const findTextWithinBounds: (text: string, x: number, y: number, w: number, h: number, options?: TextMatchOptions, config?: ROConfig) => Region | undefined;
 /**
@@ -80,7 +80,7 @@ export declare const findTextWithinBounds: (text: string, x: number, y: number,
  * @param bottom 下边界偏移量（像素）
  * @param options 搜索选项
  * @param config 识别对象配置
- * @returns 如果找到匹配的文本区域，则返回该区域
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export declare const findTextBetweenCoordinates: (text: string, left: number, top: number, right: number, bottom: number, options?: TextMatchOptions, config?: ROConfig) => Region | undefined;
 /**
@@ -89,7 +89,7 @@ export declare const findTextBetweenCoordinates: (text: string, left: number, to
  * @param direction 搜索方向
  * @param options 搜索选项
  * @param config 识别对象配置
- * @returns 如果找到匹配的文本区域，则返回该区域
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export declare const findTextInDirection: (text: string, direction: MatchDirection, options?: TextMatchOptions, config?: ROConfig) => Region | undefined;
 /** 列表视图参数 */
@@ -112,10 +112,11 @@ export type ListView = {
  * @param condition 查找条件
  * @param listView 列表视图参数
  * @param retryOptions 重试选项
- * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：取上半部分）
+ * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：底半区）
+ * @param threshold 采样区域匹配阈值（默认：0.9）
  * @returns 如果找到匹配的区域，则返回该区域，否则返回 undefined
  */
-export declare const findWithinListView: (condition: (listViewRegion: ImageRegion) => Region | undefined, listView: ListView, retryOptions?: RetryOptions, sampling?: (listViewRegion: ImageRegion) => ImageRegion) => Promise<Region | undefined>;
+export declare const findWithinListView: (condition: (listViewRegion: ImageRegion) => Region | undefined, listView: ListView, retryOptions?: RetryOptions, sampling?: (listViewRegion: ImageRegion) => ImageRegion, threshold?: number) => Promise<Region | undefined>;
 /**
  * 在列表视图中滚动搜索文本
  * @param text 待搜索文本
@@ -123,15 +124,19 @@ export declare const findWithinListView: (condition: (listViewRegion: ImageRegio
  * @param matchOptions 搜索选项
  * @param retryOptions 重试选项
  * @param config 识别对象配置
+ * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：底半区）
+ * @param threshold 采样区域匹配阈值（默认：0.9）
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
-export declare const findTextWithinListView: (text: string, listView: ListView, matchOptions?: TextMatchOptions, retryOptions?: RetryOptions, config?: ROConfig, sampling?: (listViewRegion: ImageRegion) => ImageRegion) => Promise<Region | undefined>;
+export declare const findTextWithinListView: (text: string, listView: ListView, matchOptions?: TextMatchOptions, retryOptions?: RetryOptions, config?: ROConfig, sampling?: (listViewRegion: ImageRegion) => ImageRegion, threshold?: number) => Promise<Region | undefined>;
 /**
  * 在列表视图中查找图像
  * @param image 图片路径 或 图片Mat
  * @param listView 列表视图参数
- * @param config 识别对象配置
  * @param retryOptions 重试选项
+ * @param config 识别对象配置
+ * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：底半区）
+ * @param threshold 采样区域匹配阈值（默认：0.9）
  * @returns 如果找到匹配的区域，则返回该区域，否则返回 undefined
  */
-export declare const findImageWithinListView: (image: string | ImageMat, listView: ListView, config?: ROConfig, retryOptions?: RetryOptions, sampling?: (listViewRegion: ImageRegion) => ImageRegion) => Promise<Region | undefined>;
+export declare const findImageWithinListView: (image: string | ImageMat, listView: ListView, retryOptions?: RetryOptions, config?: ROConfig, sampling?: (listViewRegion: ImageRegion) => ImageRegion, threshold?: number) => Promise<Region | undefined>;

package/dist/ocr.js

@@ -17,7 +17,7 @@ const directionToBounds = (direction) => {
  * 在整个画面内搜索图片
  * @param image 图片路径 或 图片Mat
  * @param config 识别对象配置
- * @returns 如果找到匹配的图片区域，则返回该区域
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export const findImage = (image, config = {}) => {
     const ir = captureGameRegion();
@@ -45,7 +45,7 @@ export const findImage = (image, config = {}) => {
  * @param w 宽度
  * @param h 高度
  * @param config 识别对象配置
- * @returns 如果找到匹配的图片区域，则返回该区域
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export const findImageWithinBounds = (image, x, y, w, h, config = {}) => {
     const ir = captureGameRegion();
@@ -73,7 +73,7 @@ export const findImageWithinBounds = (image, x, y, w, h, config = {}) => {
  * @param right 右边界偏移量（像素）
  * @param bottom 下边界偏移量（像素）
  * @param config 识别对象配置
- * @returns 如果找到匹配的图片区域，则返回该区域
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export const findImageBetweenCoordinates = (image, left, top, right, bottom, config = {}) => {
     return findImageWithinBounds(image, left, top, right - left, bottom - top, config);
@@ -83,7 +83,7 @@ export const findImageBetweenCoordinates = (image, left, top, right, bottom, con
  * @param image 图片路径 或 图片Mat
  * @param direction 搜索方向
  * @param config 识别对象配置
- * @returns 如果找到匹配的图片区域，则返回该区域
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export const findImageInDirection = (image, direction, config = {}) => {
     const { x, y, w, h } = directionToBounds(direction);
@@ -122,7 +122,7 @@ const textMatch = (text, searchText, options) => {
  * @param text 待搜索文本
  * @param options 搜索选项
  * @param config 识别对象配置
- * @returns 如果找到匹配的文本区域，则返回该区域
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export const findText = (text, options, config = {}) => {
     const ir = captureGameRegion();
@@ -151,7 +151,7 @@ export const findText = (text, options, config = {}) => {
  * @param h 高度
  * @param options 搜索选项
  * @param config 识别对象配置
- * @returns 如果找到匹配的文本区域，则返回该区域
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export const findTextWithinBounds = (text, x, y, w, h, options, config = {}) => {
     const ir = captureGameRegion();
@@ -180,7 +180,7 @@ export const findTextWithinBounds = (text, x, y, w, h, options, config = {}) =>
  * @param bottom 下边界偏移量（像素）
  * @param options 搜索选项
  * @param config 识别对象配置
- * @returns 如果找到匹配的文本区域，则返回该区域
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export const findTextBetweenCoordinates = (text, left, top, right, bottom, options, config = {}) => {
     return findTextWithinBounds(text, left, top, right - left, bottom - top, options, config);
@@ -191,7 +191,7 @@ export const findTextBetweenCoordinates = (text, left, top, right, bottom, optio
  * @param direction 搜索方向
  * @param options 搜索选项
  * @param config 识别对象配置
- * @returns 如果找到匹配的文本区域，则返回该区域
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export const findTextInDirection = (text, direction, options, config = {}) => {
     const { x, y, w, h } = directionToBounds(direction);
@@ -202,28 +202,39 @@ export const findTextInDirection = (text, direction, options, config = {}) => {
  * @param condition 查找条件
  * @param listView 列表视图参数
  * @param retryOptions 重试选项
- * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：取上半部分）
+ * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：底半区）
+ * @param threshold 采样区域匹配阈值（默认：0.9）
  * @returns 如果找到匹配的区域，则返回该区域，否则返回 undefined
  */
-export const findWithinListView = async (condition, listView, retryOptions, sampling) => {
+export const findWithinListView = async (condition, listView, retryOptions, sampling, threshold = 0.9) => {
     const { x, y, w, h, lineHeight, scrollLines = 1, paddingX = 10, paddingY = 10 } = listView;
-    const { maxAttempts = 99, retryInterval = 1000 } = retryOptions || {};
-    sampling = sampling || (r => r.deriveCrop(0, 0, r.width, Math.floor(r.height / 2)));
+    const { maxAttempts = 99, retryInterval = 1200 } = retryOptions || {};
+    sampling ??= r => r.deriveCrop(1, r.height * 0.5, r.width - 1, r.height * 0.5);
     const captureListViewRegion = () => captureGameRegion().deriveCrop(x, y, w, h);
-    let _lvr;
-    const isReachedBottom = () => {
-        const region = sampling(captureListViewRegion());
-        if (region?.isExist()) {
-            if (_lvr?.find(RecognitionObject.templateMatch(region.srcMat))) {
+    const isReachedBottom = (() => {
+        let lastCaptured;
+        return () => {
+            const newRegion = captureListViewRegion();
+            if (!newRegion?.isExist())
                 return true;
+            try {
+                if (!lastCaptured)
+                    return false;
+                const oldRegion = sampling(lastCaptured);
+                if (!oldRegion?.isExist())
+                    return true;
+                // 根据采样区域画面是否变化，判断列表是否触底
+                const ro = RecognitionObject.templateMatch(oldRegion.srcMat);
+                ro.threshold = threshold;
+                ro.use3Channels = true;
+                ro.initTemplate();
+                return newRegion.find(ro)?.isExist();
             }
-            else {
-                _lvr = region;
-                return false;
+            finally {
+                lastCaptured = newRegion;
             }
-        }
-        return true; // 异常情况: 无法获取列表视图截图
-    };
+        };
+    })();
     const isFoundOrReachedBottom = await waitForAction(() => condition(captureListViewRegion())?.isExist() || isReachedBottom(), async () => {
         moveMouseTo(x + w - paddingX, y + paddingY); // 移动到滚动条附近
         await sleep(50);
@@ -238,9 +249,11 @@ export const findWithinListView = async (condition, listView, retryOptions, samp
  * @param matchOptions 搜索选项
  * @param retryOptions 重试选项
  * @param config 识别对象配置
+ * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：底半区）
+ * @param threshold 采样区域匹配阈值（默认：0.9）
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
-export const findTextWithinListView = async (text, listView, matchOptions, retryOptions, config = {}, sampling) => {
+export const findTextWithinListView = async (text, listView, matchOptions, retryOptions, config = {}, sampling, threshold = 0.9) => {
     const ro = RecognitionObject.ocrThis;
     if (Object.keys(config).length > 0) {
         Object.assign(ro, config) && ro.initTemplate();
@@ -249,17 +262,19 @@ export const findTextWithinListView = async (text, listView, matchOptions, retry
         return findFirstRegion(lvr, ro, region => {
             return region.isExist() && textMatch(region.text, text, matchOptions);
         });
-    }, listView, retryOptions, sampling);
+    }, listView, retryOptions, sampling, threshold);
 };
 /**
  * 在列表视图中查找图像
  * @param image 图片路径 或 图片Mat
  * @param listView 列表视图参数
- * @param config 识别对象配置
  * @param retryOptions 重试选项
+ * @param config 识别对象配置
+ * @param sampling 区域采样函数，通过采样区域画面变化判断列表是否触底（默认：底半区）
+ * @param threshold 采样区域匹配阈值（默认：0.9）
  * @returns 如果找到匹配的区域，则返回该区域，否则返回 undefined
  */
-export const findImageWithinListView = async (image, listView, config = {}, retryOptions, sampling) => {
+export const findImageWithinListView = async (image, listView, retryOptions, config = {}, sampling, threshold = 0.9) => {
     const mat = typeof image === "string" ? file.readImageMatSync(image) : image;
     const ro = RecognitionObject.templateMatch(mat);
     if (Object.keys(config).length > 0) {
@@ -268,5 +283,5 @@ export const findImageWithinListView = async (image, listView, config = {}, retr
     return findWithinListView(ir => {
         const region = ir.find(ro);
         return region.isExist() ? region : undefined;
-    }, listView, retryOptions, sampling);
+    }, listView, retryOptions, sampling, threshold);
 };

package/dist/store.js

@@ -60,7 +60,7 @@ export const useStore = (name) => {
  * @param defaults 默认值数据对象
  */
 export const useStoreWithDefaults = (name, defaults) => {
-    const store = useStore(name);
-    Object.assign(store, deepMerge(defaults, store));
-    return store;
+    const newStore = useStore(name);
+    Object.assign(newStore, deepMerge(defaults, newStore));
+    return newStore;
 };

package/package.json

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