@bettergi/utils 0.0.9 → 0.0.11

package/README.md

@@ -74,7 +74,14 @@ const t3 = findTextWithinBounds("确认", false, true, 960, 540, 960, 540);
 > 对脚本开发过程中常见工作流的抽象，例如：等待 XXX 完成/出现/消失。
 
 ```ts
-import { findImageInDirection, waitUntil } from "@bettergi/utils";
+import {
+  assertExists,
+  assertNotExists,
+  findImageInDirection,
+  findTextInDirection,
+  findTextWithinBounds,
+  waitUntil
+} from "@bettergi/utils";
 
 // 等待直到找不到[关闭按钮] 或 5秒后超时，每隔1秒检查一次，期间按 Esc 键
 const done = await waitUntil(
@@ -84,6 +91,19 @@ const done = await waitUntil(
   () => keyPress("ESCAPE")
 );
 if (!done) throw new Error("关闭页面超时");
+
+// 断言 "世界等级" 区域存在 或 5秒后超时抛出异常，每隔1秒检查一次，期间按 Esc 键
+await assertExists(
+  () => findTextInDirection("世界等级", false, true, "north-west"),
+  "打开派蒙菜单超时",
+  5000,
+  1000,
+  () => keyPress("ESCAPE")
+);
+
+// 断言 "购买" 区域不存在 或 5秒后超时抛出异常，每隔1秒检查一次，期间如果存在 "购买" 按钮则点击
+const findButton = () => findTextWithinBounds("购买", true, true, 500, 740, 900, 110);
+await assertNotExists(findButton, "点击购买按钮超时", 5000, 1000, () => findButton()?.click());
 ```
 
 ### 鼠标操作

package/dist/flow.d.ts

@@ -7,4 +7,24 @@
  * @returns - true  在超时前条件已满足
  *          - false 在超时后条件仍未满足
  */
-export declare const waitUntil: (condition: (context: Record<string, any>) => boolean, timeout?: number, interval?: number, action?: (context: Record<string, any>) => void) => Promise<boolean>;
+export declare const waitUntil: (condition: (context: Record<string, any>) => boolean, timeout?: number, interval?: number, action?: (context: Record<string, any>) => Promise<void> | void) => Promise<boolean>;
+/**
+ * 断言区域存在
+ * @param 获取区域的函数
+ * @param message 错误信息
+ * @param timeout 超时时间（毫秒），默认 3000 毫秒
+ * @param interval 等待间隔（毫秒），默认 300 毫秒
+ * @param action 每次等待循环中执行的操作（可选）
+ * @throws 如果区域在超时时间内未找到则抛出错误
+ */
+export declare const assertExists: (regionProvider: () => Region | undefined, message?: string, timeout?: number, interval?: number, action?: (context: Record<string, any>) => Promise<void> | void) => Promise<void>;
+/**
+ * 断言区域不存在
+ * @param 获取区域的函数
+ * @param message 错误信息
+ * @param timeout 超时时间（毫秒），默认 3000 毫秒
+ * @param interval 等待间隔（毫秒），默认 300 毫秒
+ * @param action 每次等待循环中执行的操作（可选）
+ * @throws 如果区域在超时时间内仍然存在则抛出错误
+ */
+export declare const assertNotExists: (regionProvider: () => Region | undefined, message?: string, timeout?: number, interval?: number, action?: (context: Record<string, any>) => Promise<void> | void) => Promise<void>;

package/dist/flow.js

@@ -1,3 +1,7 @@
+/** 默认超时时间（毫秒） */
+const defaultTimeout = 3 * 1000;
+/** 默认等待间隔（毫秒） */
+const defaultInterval = 300;
 /**
  * 等待直到条件满足或超时
  * @param condition 等待的条件判断函数，返回 true 表示条件满足
@@ -7,14 +11,42 @@
  * @returns - true  在超时前条件已满足
  *          - false 在超时后条件仍未满足
  */
-export const waitUntil = async (condition, timeout, interval, action) => {
+export const waitUntil = async (condition, timeout = defaultTimeout, interval = defaultInterval, action) => {
     const context = {};
-    const deadline = Date.now() + (timeout ?? 3 * 1000);
+    const deadline = Date.now() + timeout;
     while (Date.now() < deadline) {
         if (condition(context))
             return true;
-        action?.(context);
-        await sleep(interval ?? 300);
+        await action?.(context);
+        await sleep(interval);
     }
     return false;
 };
+/**
+ * 断言区域存在
+ * @param 获取区域的函数
+ * @param message 错误信息
+ * @param timeout 超时时间（毫秒），默认 3000 毫秒
+ * @param interval 等待间隔（毫秒），默认 300 毫秒
+ * @param action 每次等待循环中执行的操作（可选）
+ * @throws 如果区域在超时时间内未找到则抛出错误
+ */
+export const assertExists = async (regionProvider, message = "断言区域存在失败", timeout = defaultTimeout, interval = defaultInterval, action) => {
+    const ok = await waitUntil(() => regionProvider() !== undefined, timeout, interval, action);
+    if (!ok)
+        throw new Error(message);
+};
+/**
+ * 断言区域不存在
+ * @param 获取区域的函数
+ * @param message 错误信息
+ * @param timeout 超时时间（毫秒），默认 3000 毫秒
+ * @param interval 等待间隔（毫秒），默认 300 毫秒
+ * @param action 每次等待循环中执行的操作（可选）
+ * @throws 如果区域在超时时间内仍然存在则抛出错误
+ */
+export const assertNotExists = async (regionProvider, message = "断言区域不存在失败", timeout = defaultTimeout, interval = defaultInterval, action) => {
+    const ok = await waitUntil(() => regionProvider() === undefined, timeout, interval, action);
+    if (!ok)
+        throw new Error(message);
+};

package/dist/game.js

@@ -1,4 +1,4 @@
-import { waitUntil } from "./flow";
+import { assertExists, assertNotExists } from "./flow";
 import { mouseSlide } from "./mouse";
 import { findTextInDirection, findTextWithinBounds, findTextWithinListView } from "./ocr";
 /**
@@ -8,10 +8,7 @@ export const openPaimonMenu = async () => {
     // 1.返回主界面
     await genshin.returnMainUi();
     // 2.打开派蒙菜单
-    const findWorldLevel = () => findTextInDirection("世界等级", false, true, "north-west");
-    const ok = await waitUntil(() => findWorldLevel() !== undefined, 5000, 1000, () => keyPress("ESCAPE"));
-    if (!ok)
-        throw new Error("打开派蒙菜单超时");
+    await assertExists(() => findTextInDirection("世界等级", false, true, "north-west"), "打开派蒙菜单超时", 5000, 1000, () => keyPress("ESCAPE"));
 };
 /**
  * 打开游戏菜单（左侧按钮）
@@ -19,11 +16,11 @@ export const openPaimonMenu = async () => {
  * @param reverse 是否反向搜索（可选）
  * @param config 搜索参数（可选）
  */
-export const openMenu = async (name, reverse, config) => {
+export const openMenu = async (name, reverse = false, config = {}) => {
     // 1.打开派蒙菜单
     await openPaimonMenu();
     // 2.搜索菜单按钮
-    const { x = 50, step = 30, timeout = 3000 } = config || {};
+    const { x = 50, step = 30, timeout = 3000 } = config;
     const findTooltip = () => findTextWithinBounds(name, false, true, 0, 0, x + 150, genshin.height);
     let result = undefined;
     const steps = Math.ceil(genshin.height / step);
@@ -31,17 +28,15 @@ export const openMenu = async (name, reverse, config) => {
         const o = i * step;
         const y = reverse ? genshin.height - o : o;
         moveMouseTo(x, y);
-        await sleep(30);
+        await sleep(30); // 等待提示文字出现
         if ((result = findTooltip()) !== undefined)
             break;
     }
     // 3.点击菜单按钮
     if (result != undefined) {
-        const ok = await waitUntil(() => findTooltip() === undefined, timeout, 1000, () => {
+        await assertNotExists(findTooltip, `打开菜单 ${name} 超时`, timeout, 1000, () => {
             click(x, result.y);
         });
-        if (!ok)
-            throw new Error(`打开菜单 ${name} 超时`);
     }
     else {
         throw new Error(`打开菜单 ${name} 失败`);
@@ -52,11 +47,11 @@ export const openMenu = async (name, reverse, config) => {
  * @param name 菜单页面名称
  * @param config 菜单页面视图参数
  */
-export const openMenuPage = async (name, config) => {
+export const openMenuPage = async (name, config = {}) => {
     // 1.打开派蒙菜单
     await openPaimonMenu();
     // 2.搜索菜单页面
-    const { x = 100, y = 330, w = 670, h = 730, lineHeight = 142 } = config || {};
+    const { x = 100, y = 330, w = 670, h = 730, lineHeight = 142 } = config;
     const pageButton = await findTextWithinListView(name, false, true, {
         x,
         y,
@@ -75,11 +70,11 @@ export const openMenuPage = async (name, config) => {
  * @param period 时间段
  * @param config 时钟参数
  */
-export const setTime = async (period, config) => {
+export const setTime = async (period, config = {}) => {
     // 1.打开时间页面
     await openMenu("时间", true);
     // 2.拨动指针
-    const { centerX = 1440, centerY = 502, radius = 400, offset = 5 } = config || {};
+    const { centerX = 1440, centerY = 502, radius = 400, offset = 5 } = config;
     const index = ["night", "morning", "noon", "evening"].indexOf(period);
     const periodsDirections = [
         () => mouseSlide(centerX, centerY, centerX - offset, centerY + radius),
@@ -91,13 +86,9 @@ export const setTime = async (period, config) => {
     for (const job of jobs)
         await job();
     // 3.点击确认按钮，等待调整结束
-    const findTooShort = () => findTextInDirection("时间少于", true, true, "south-east");
-    const findConfirmButton = () => findTextInDirection("确认", false, true, "south-east");
-    const ok = await waitUntil(() => findTooShort() !== undefined, 20 * 1000, 1000, () => {
-        findConfirmButton()?.click();
+    await assertExists(() => findTextInDirection("时间少于", true, true, "south-east"), "调整时间超时", 20 * 1000, 1000, () => {
+        findTextInDirection("确认", false, true, "south-east")?.click();
     });
-    if (!ok)
-        throw new Error("调整时间超时");
     // 4.返回主界面
     await genshin.returnMainUi();
 };

package/dist/http.js

@@ -6,8 +6,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");
+export const requestForBody = async (method, url, body = "null", headers) => {
+    const resp = await http.request(method, url, body, headers ? JSON.stringify(headers) : "null");
     if (resp.status_code >= 200 && resp.status_code < 400) {
         return resp.body;
     }

package/dist/mouse.js

@@ -10,36 +10,32 @@ const _simulateScroll = async (scrollAmountInClicks, times) => {
  * @param height 滚动高度
  * @param algorithm 自定义滚动算法函数，接收高度参数并返回滚动次数（默认算法为每18像素滚动一次）
  */
-export const mouseScrollUp = (height, algorithm) => {
-    const scrollAlgorithm = algorithm ?? (h => Math.floor(h / 18));
-    const scrollTimes = scrollAlgorithm(height);
-    return _simulateScroll(120, scrollTimes);
+export const mouseScrollUp = (height, algorithm = h => Math.floor(h / 18)) => {
+    return _simulateScroll(120, algorithm(height));
 };
 /**
  * 鼠标滚轮向下滚动指定高度
  * @param height 滚动高度
  * @param algorithm 自定义滚动算法函数，接收高度参数并返回滚动次数（默认算法为每18像素滚动一次）
  */
-export const mouseScrollDown = (height, algorithm) => {
-    const scrollAlgorithm = algorithm ?? (h => Math.floor(h / 18));
-    const scrollTimes = scrollAlgorithm(height);
-    return _simulateScroll(-120, scrollTimes);
+export const mouseScrollDown = (height, algorithm = h => Math.floor(h / 18)) => {
+    return _simulateScroll(-120, algorithm(height));
 };
 /**
  * 鼠标滚轮向上滚动指定行数
  * @param lines 滚动行数
  * @param lineHeight 行高（默认值为175像素）
  */
-export const mouseScrollUpLines = (lines, lineHeight) => {
-    return mouseScrollUp(lines * (lineHeight ?? 175));
+export const mouseScrollUpLines = (lines, lineHeight = 175) => {
+    return mouseScrollUp(lines * lineHeight);
 };
 /**
  * 鼠标滚轮向下滚动指定行数
  * @param lines 滚动行数
  * @param lineHeight 行高（默认值为175像素）
  */
-export const mouseScrollDownLines = (lines, lineHeight) => {
-    return mouseScrollDown(lines * (lineHeight ?? 175));
+export const mouseScrollDownLines = (lines, lineHeight = 175) => {
+    return mouseScrollDown(lines * lineHeight);
 };
 /**
  * 鼠标拖拽滑动到指定位置
@@ -50,11 +46,11 @@ export const mouseScrollDownLines = (lines, lineHeight) => {
  */
 export const mouseSlide = async (x1, y1, x2, y2) => {
     moveMouseTo(x1, y1);
-    await sleep(50);
+    await sleep(100);
     leftButtonDown();
-    await sleep(50);
+    await sleep(100);
     moveMouseTo(x2, y2);
-    await sleep(50);
+    await sleep(100);
     leftButtonUp();
 };
 /**

package/dist/ocr.js

@@ -119,7 +119,7 @@ export const findTextInDirection = (text, contains, ignoreCase, direction) => {
  * @param timeout 搜索超时
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
-export const findTextWithinListView = async (text, contains, ignoreCase, listView, timeout) => {
+export const findTextWithinListView = async (text, contains, ignoreCase, listView, timeout = 30 * 1000) => {
     const { x, y, w, h, maxListItems, lineHeight, padding = 10 } = listView;
     const find = () => {
         return findTextWithinBounds(text, contains, ignoreCase, x, y, w, h);
@@ -141,7 +141,7 @@ export const findTextWithinListView = async (text, contains, ignoreCase, listVie
             return true;
         }
     };
-    const ok = await waitUntil(() => find() != undefined || isBottomTouched(), timeout ?? 30 * 1000, 1000, async () => {
+    const ok = await waitUntil(() => find() != undefined || isBottomTouched(), timeout, 1000, async () => {
         moveMouseTo(x + w - padding, y + padding);
         await mouseScrollDownLines(maxListItems, lineHeight);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/utils",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "开发 BetterGI 脚本常用工具集",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",
@@ -33,7 +33,7 @@
     "build": "tsc"
   },
   "devDependencies": {
-    "@bettergi/types": "^0.0.13",
-    "typescript": "5.6.3"
+    "@bettergi/types": "^0.0.14",
+    "typescript": "^5.9.3"
   }
 }

package/dist/action.d.ts

@@ -1,10 +0,0 @@
-/**
- * 等待直到条件满足或超时
- * @param condition 等待的条件判断函数，返回 true 表示条件满足
- * @param timeout 超时时间（毫秒），默认 5000 毫秒
- * @param interval 等待间隔（毫秒），默认 200 毫秒
- * @param action 每次等待循环中执行的操作（可选）
- * @returns - true  在超时前条件已满足
- *          - false 在超时后条件仍未满足
- */
-export declare const waitUntil: (condition: (context: Record<string, any>) => boolean, timeout?: number, interval?: number, action?: (context: Record<string, any>) => void) => Promise<boolean>;

package/dist/action.js

@@ -1,20 +0,0 @@
-/**
- * 等待直到条件满足或超时
- * @param condition 等待的条件判断函数，返回 true 表示条件满足
- * @param timeout 超时时间（毫秒），默认 5000 毫秒
- * @param interval 等待间隔（毫秒），默认 200 毫秒
- * @param action 每次等待循环中执行的操作（可选）
- * @returns - true  在超时前条件已满足
- *          - false 在超时后条件仍未满足
- */
-export const waitUntil = async (condition, timeout, interval, action) => {
-    const context = {};
-    const deadline = Date.now() + (timeout ?? 5 * 1000);
-    while (Date.now() < deadline) {
-        if (condition(context))
-            return true;
-        action?.(context);
-        await sleep(interval ?? 200);
-    }
-    return false;
-};