@bettergi/utils 0.1.11 → 0.1.13

package/README.md

@@ -50,20 +50,26 @@ await navigateToTab(() => {
 // 在整个画面内搜索图片，找不到返回 undefined
 const i1 = findImage("assets/关闭.png", { use3Channels: true }); // 匹配颜色
 
-// 在指定方向上搜索图片，找不到返回 undefined
-const i2 = findImageInDirection("assets/关闭.png", "north-east");
-
 // 在指定区域内搜索图片，找不到返回 undefined
-const i3 = findImageWithinBounds("assets/关闭.png", 960, 0, 960, 1080);
+const i2 = 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 });
 ```
 
 ### 行为流程
@@ -71,28 +77,24 @@ const t3 = findTextWithinBounds("确认", 960, 540, 960, 540);
 > 对脚本开发过程中常见工作流的抽象，例如: 等待/断言 操作/元素/区域 完成/出现/消失。
 
 ```ts
-// 等待直到找不到 [关闭按钮] ，重试5次，每隔1秒重试一次，期间按 Esc 键
+// 等待直到找不到 [关闭按钮] ，重试5次，每隔1秒重试一次（默认参数），期间按 Esc 键
 const done = await waitForAction(
   () => findImageInDirection("assets/关闭.png", "north-east") === undefined,
-  () => keyPress("ESCAPE"),
-  { maxAttempts: 5, retryInterval: 1000 }
+  () => keyPress("ESCAPE")
 );
 if (!done) throw new Error("关闭页面超时");
 
-// 断言 "生日" 文字区域即将出现，重试5次，每隔1秒重试一次，期间按 Esc 键
+// 断言 "生日" 文字区域即将出现，重试10次，每隔1秒重试一次，期间按 Esc 键
 await assertRegionAppearing(
   () => findTextInDirection("生日", "north-west"),
   "打开派蒙菜单超时",
   () => keyPress("ESCAPE"),
-  { maxAttempts: 5, retryInterval: 1000 }
+  { maxAttempts: 10, retryInterval: 1000 }
 );
 
-// 断言 "购买" 区域不存在，否则抛出异常，重试5次，每隔1秒重试一次，期间如果存在 "购买" 按钮则点击
+// 断言 "购买" 文字区域即将消失，重试5次，每隔1秒重试一次（默认参数），期间如果存在 "购买" 按钮则点击
 const findButton = () => findTextWithinBounds("购买", 500, 740, 900, 110);
-await assertRegionDisappearing(findButton, "点击购买按钮超时", () => findButton()?.click(), {
-  maxAttempts: 5,
-  retryInterval: 1000
-});
+await assertRegionDisappearing(findButton, "点击购买按钮超时", () => findButton()?.click());
 ```
 
 ### 鼠标操作
@@ -119,27 +121,54 @@ await mouseScrollUpLines(99);
 await mouseScrollDownLines(1, 115);
 ```
 
-### 数据存储
+### 状态管理和持久化
 
-> 对象数据持久化，通过 Proxy 实现自动存储。从而可以无感知地读取/更新数据，而无需考虑如何持久化。
+> 基于深度 Proxy 实现的对象数据持久化，能够在数据被修改时自动同步至文件。使开发其能够像操作普通对象一样进行数据读写，而无需关心底层的持久化细节。
 
 ```ts
 // 创建/读取存储对象，保存到存储文件 store/my-data.json 中
-const state = useStore<{ lastUsedTime?: number; count: number }>("my-data");
+const store = useStore<{ lastUsedTime?: number; count: number }>("my-data");
 // 默认值版本
 // const state = useStoreWithDefaults("my-data", { lastUsedTime: 0, count: 0 });
 
-if (state?.lastUsedTime) {
-  log.info(`欢迎回来！上次使用时间: ${state.lastUsedTime}，计数器已累计至: ${state.count}`);
+if (store?.lastUsedTime) {
+  log.info(`欢迎回来！上次使用时间: ${store.lastUsedTime}，计数器已累计至: ${store.count}`);
 }
 try {
   // 模拟脚本运行期间状态的变化
   for (let i = 0; i < Math.floor(Math.random() * 100); i++) {
-    state.count = (state.count || 0) + 1; // 自动同步保存到文件
+    store.count = (store.count || 0) + 1; // 自动保存到文件
   }
 } finally {
-  state.lastUsedTime = Date.now(); // 自动同步保存到文件
+  store.lastUsedTime = Date.now(); // 自动保存到文件
+}
+```
+
+### 进度追踪
+
+> 创建进度追踪器并设置总进度，通过递进函数增加进度，开发者可以获取当前进度、当前耗时、平均耗时、预估剩余时间等数据。
+
+```ts
+const total = 100;
+// 创建进度追踪器，使用默认日志记录器（可配置），打印间隔最小3秒
+const tracker = new ProgressTracker(total, { interval: 3000 });
+for (let i = 0; i < total; i++) {
+  await sleep(Math.round(Math.random() * 200));
+  // 递进并尝试打印进度和消息
+  tracker.tick({ message: "等待任务完成..." });
+
+  // 也可以主动追踪，使用传递的进度信息自主控制打印时机和内容
+  // tracker.track((progress, shouldPrint, printed) => {
+  //   if (!shouldPrint()) return;
+  //   log.info(
+  //     "[进度: {pct} 预计剩余时间: {eta}]: 等待任务完成...",
+  //     progress.formatted.percentage,
+  //     progress.formatted.remaining
+  //   );
+  //   printed();
+  // });
 }
+tracker.complete(`执行完成`);
 ```
 
 ### 网络请求

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export * from "./misc";
 export * from "./mouse";
 /** 图像识别 */
 export * from "./ocr";
+/** 进度追踪 */
+export * from "./progress";
 /** 数据存储 */
 export * from "./store";
 /** 日期时间 */

package/dist/index.js

@@ -14,6 +14,8 @@ export * from "./misc";
 export * from "./mouse";
 /** 图像识别 */
 export * from "./ocr";
+/** 进度追踪 */
+export * from "./progress";
 /** 数据存储 */
 export * from "./store";
 /** 日期时间 */

package/dist/mouse.d.ts

@@ -1,6 +1,8 @@
 export type MouseWaypointsOptions = {
     /** 是否按住鼠标左键拖动 */
     shouldDrag?: boolean;
+    /** 移动延时（毫秒） */
+    delay?: number;
     /** 超时时间（毫秒，默认: 不超时） */
     timeout?: number;
 };

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,7 +1,9 @@
 import { RetryOptions } from "./workflow";
+/** 识别对象实例 */
 export type ROInstance = InstanceType<typeof RecognitionObject>;
+/** 识别对象配置 */
 export type ROConfig = Partial<{
-    [K in keyof ROInstance]: ROInstance[K];
+    [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"; /** 左上四分之一 */
 /**
@@ -22,6 +24,17 @@ export declare const findImage: (path: string, config?: ROConfig) => Region | un
  * @returns 如果找到匹配的图片区域，则返回该区域
  */
 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 图片路径
@@ -57,6 +70,18 @@ export declare const findText: (text: string, options?: TextMatchOptions, 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 findTextBetweenCoordinates: (text: string, left: number, top: number, right: number, bottom: number, options?: TextMatchOptions, config?: ROConfig) => Region | undefined;
 /**
  * 在指定方向上搜索文本
  * @param text 待搜索文本

package/dist/ocr.js

@@ -65,6 +65,19 @@ export const findImageWithinBounds = (path, x, y, w, h, config = {}) => {
         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 图片路径
@@ -134,6 +147,20 @@ export const findTextWithinBounds = (text, x, y, w, h, options, config = {}) =>
         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 待搜索文本
@@ -179,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/progress.d.ts

@@ -0,0 +1,56 @@
+/** 进度信息 */
+export type Progress = {
+    /** 当前进度 */
+    current: number;
+    /** 总进度 */
+    total: number;
+    /** 完成百分比 */
+    percentage: number;
+    /** 已用时间（毫秒） */
+    elapsed: number;
+    /** 平均每单位时间（毫秒） */
+    average: number;
+    /** 预计剩余时间（毫秒） */
+    remaining: number;
+    /** 格式化后的进度信息 */
+    formatted: {
+        percentage: string;
+        elapsed: string;
+        average: string;
+        remaining: string;
+    };
+};
+/** 进度日志记录器 */
+export type ProgressLogger = (message: string, progress: Progress) => void;
+export type ProgressTrackerConfig = {
+    /** 日志记录器 */
+    logger?: ProgressLogger;
+    /** 节流间隔（毫秒），默认3000 */
+    interval?: number;
+};
+/** 进度递进选项 */
+export type ProgressTickOptions = {
+    /** 递进后打印消息 */
+    message?: string;
+    /** 递进的幅度 */
+    increment?: number;
+};
+/** 进度追踪器 */
+export declare class ProgressTracker {
+    private total;
+    private current;
+    private startTime;
+    private readonly logger;
+    private readonly interval;
+    private lastPrintTime;
+    constructor(total: number, config?: ProgressTrackerConfig);
+    private readonly defaultLogger;
+    tick(options?: ProgressTickOptions): void;
+    track(callback: (progress: Progress, shouldPrint: () => boolean, printed: () => void) => void): void;
+    complete(message: string): void;
+    reset(): void;
+    private print;
+    private shouldPrint;
+    private printed;
+    getProgress(): Progress;
+}

package/dist/progress.js

@@ -0,0 +1,73 @@
+import { formatDurationAsClock, formatDurationAsReadable } from "./time";
+/** 进度追踪器 */
+export class ProgressTracker {
+    total = 0;
+    current = 0;
+    startTime = Date.now();
+    logger;
+    interval;
+    lastPrintTime = 0;
+    constructor(total, config) {
+        const { logger, interval: throttleInterval = 3000 } = config || {};
+        this.total = total;
+        this.logger = logger || this.defaultLogger;
+        this.interval = throttleInterval;
+    }
+    defaultLogger = (message, progress) => {
+        log.info("[🚧 {pct} ⏳ {eta}]: {msg}", progress.formatted.percentage.padStart(6), progress.current > 0 && progress.elapsed > 0 ? progress.formatted.remaining : "--:--:--", message);
+    };
+    tick(options) {
+        const { message, increment = 1 } = options || {};
+        this.current = Math.min(this.current + increment, this.total);
+        if (message)
+            this.print(message);
+    }
+    track(callback) {
+        const progress = this.getProgress();
+        const shouldPrint = this.shouldPrint.bind(this);
+        const printed = this.printed.bind(this);
+        callback(progress, shouldPrint, printed);
+    }
+    complete(message) {
+        this.current = this.total;
+        if (message)
+            this.print(message, true);
+    }
+    reset() {
+        this.current = 0;
+        this.startTime = Date.now();
+        this.lastPrintTime = 0;
+    }
+    print(message, force = false) {
+        if (force || this.shouldPrint()) {
+            this.logger(message, this.getProgress());
+            this.printed();
+        }
+    }
+    shouldPrint() {
+        return Date.now() - this.lastPrintTime >= this.interval;
+    }
+    printed() {
+        this.lastPrintTime = Date.now();
+    }
+    getProgress() {
+        const percentage = this.current / this.total;
+        const elapsed = Date.now() - this.startTime;
+        const average = this.current > 0 ? elapsed / this.current : 0;
+        const remaining = (this.total - this.current) * average;
+        return {
+            current: this.current,
+            total: this.total,
+            percentage,
+            elapsed,
+            average,
+            remaining,
+            formatted: {
+                percentage: `${(percentage * 100).toFixed(1)}%`,
+                elapsed: formatDurationAsReadable(elapsed),
+                average: formatDurationAsReadable(average),
+                remaining: formatDurationAsClock(remaining)
+            }
+        };
+    }
+}

package/dist/time.d.ts

@@ -6,3 +6,23 @@ export declare const getNextDay4AM: () => Date;
  * 获取下一个（含当日）周一凌晨4点的时间
  */
 export declare const getNextMonday4AM: () => Date;
+/**
+ * 解析时长
+ * @param duration 时长（毫秒）
+ */
+export declare const parseDuration: (duration: number) => {
+    h: number;
+    m: number;
+    s: number;
+    ms: number;
+};
+/**
+ * 将时长转换为时钟字符串
+ * @param duration 时长（毫秒）
+ */
+export declare const formatDurationAsClock: (duration: number) => string;
+/**
+ * 将时长转换为可读格式
+ * @param duration 时长（毫秒）
+ */
+export declare const formatDurationAsReadable: (duration: number) => string;

package/dist/time.js

@@ -23,3 +23,35 @@ export const getNextMonday4AM = () => {
     result.setDate(now.getDate() + daysUntilNextMonday);
     return result;
 };
+/**
+ * 解析时长
+ * @param duration 时长（毫秒）
+ */
+export const parseDuration = (duration) => {
+    return {
+        h: Math.floor(duration / 3600000),
+        m: Math.floor((duration % 3600000) / 60000),
+        s: Math.floor((duration % 60000) / 1000),
+        ms: Math.floor(duration % 1000)
+    };
+};
+/**
+ * 将时长转换为时钟字符串
+ * @param duration 时长（毫秒）
+ */
+export const formatDurationAsClock = (duration) => {
+    return Object.values(parseDuration(duration))
+        .slice(0, 3)
+        .map(num => String(num).padStart(2, "0"))
+        .join(":");
+};
+/**
+ * 将时长转换为可读格式
+ * @param duration 时长（毫秒）
+ */
+export const formatDurationAsReadable = (duration) => {
+    return Object.entries(parseDuration(duration))
+        .filter(([, value]) => value > 0)
+        .map(([unit, value]) => `${value}${unit}`)
+        .join(" ");
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/utils",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "开发 BetterGI 脚本常用工具集",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@bettergi/types": "^0.1.3",
-    "rimraf": "^6.0.1",
+    "rimraf": "^6.1.0",
     "typescript": "^5.9.3"
   }
 }