@bettergi/utils 0.1.0 → 0.1.1

package/README.md

@@ -62,7 +62,7 @@ const t3 = findTextWithinBounds("确认", 960, 540, 960, 540);
 
 ### 行为流程
 
-> 对脚本开发过程中常见工作流的抽象，例如：等待 XXX 完成/出现/消失。
+> 对脚本开发过程中常见工作流的抽象，例如: 等待/断言 操作/元素/区域 完成/出现/消失。
 
 ```ts
 // 等待直到找不到[关闭按钮] 或 5秒后超时，每隔1秒检查一次，期间按 Esc 键
@@ -106,10 +106,10 @@ await mouseScrollUp(175);
 // 鼠标滚轮向下滚动 175 像素
 await mouseScrollDown(175);
 
-// 鼠标滚轮向上滚动 99 行，行高 175（默认：背包物品行高）
+// 鼠标滚轮向上滚动 99 行，行高 175（默认: 背包物品行高）
 await mouseScrollUpLines(99);
 
-// 鼠标滚轮向下滚动 1 行，行高 115（自定义：商店物品行高）
+// 鼠标滚轮向下滚动 1 行，行高 115（自定义: 商店物品行高）
 await mouseScrollDownLines(1, 115);
 ```
 
@@ -123,7 +123,7 @@ import { useStore } from "@bettergi/utils";
 // 创建/读取存储对象，保存到存储文件 store/state.json 中
 const state = useStore<{ lastUsedTime?: number; count: number }>("state");
 if (state?.lastUsedTime) {
-  log.info(`欢迎回来！上次使用时间：${state.lastUsedTime}，计数器已累计至：${state.count}`);
+  log.info(`欢迎回来！上次使用时间: ${state.lastUsedTime}，计数器已累计至: ${state.count}`);
 }
 try {
   // 模拟脚本运行期间状态的变化
@@ -143,7 +143,7 @@ try {
 import { getForBody, postForBody } from "@bettergi/utils";
 
 // 发送 GET 请求获取响应体内容
-// 提示：需要在 `manifest.json` 文件中配置 `http_allowed_urls`，并在 调度器 -> 修改通用配置 中启用
+// 提示: 需要在 `manifest.json` 文件中配置 `http_allowed_urls`，并在 调度器 -> 修改通用配置 中启用
 const body1 = await getForBody("https://example.com/", undefined, { "User-Agent": "BetterGI" });
 const body2 = await postForBody("https://example.com/", undefined, { "User-Agent": "BetterGI" });
 log.info(`GET 请求响应体内容${body1}`);

package/dist/game.d.ts

@@ -3,11 +3,11 @@ import { ListView } from "./ocr";
  * 临时设置游戏分辨率和DPI缩放比例，执行指定动作后恢复
  * 适用于使用了鼠标移动的操作，保证在不同的分辨率和DPI下都能正确地复现鼠标操作
  * @param w 游戏宽度
- * @param y 游戏高度
+ * @param h 游戏高度
  * @param dpi 系统屏幕的DPI缩放比例
  * @param action 执行动作
  */
-export declare const withGameMetrics: <T>(w: number, y: number, dpi: number, action: () => Promise<T> | T) => Promise<T>;
+export declare const withGameMetrics: <T>(w: number, h: number, dpi: number, action: () => Promise<T> | T) => Promise<T>;
 /**
  * 打开派蒙菜单
  */
@@ -27,12 +27,17 @@ export declare const openMenu: (name: "\u62CD\u7167" | "\u516C\u544A" | "\u90AE\
  * @param name 菜单页面名称
  * @param listView 菜单页面视图参数
  */
-export declare const openMenuPage: (name: string, listView?: ListView) => Promise<void>;
+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 = {
+    /** 时钟中心X坐标 */
     centerX?: number;
+    /** 时钟中心Y坐标 */
     centerY?: number;
+    /** 偏移小时数（默认: 6） */
     offsetHours?: number;
+    /** 时钟半径（默认: 154） */
     radius?: number;
+    /** 平滑度（默认: 3） */
     smooth?: number;
 };
 /**

package/dist/game.js

@@ -5,14 +5,14 @@ import { findTextInDirection, findTextWithinBounds, findTextWithinListView } fro
  * 临时设置游戏分辨率和DPI缩放比例，执行指定动作后恢复
  * 适用于使用了鼠标移动的操作，保证在不同的分辨率和DPI下都能正确地复现鼠标操作
  * @param w 游戏宽度
- * @param y 游戏高度
+ * @param h 游戏高度
  * @param dpi 系统屏幕的DPI缩放比例
  * @param action 执行动作
  */
-export const withGameMetrics = async (w, y, dpi, action) => {
+export const withGameMetrics = async (w, h, dpi, action) => {
     const { width, height, screenDpiScale } = genshin;
     try {
-        setGameMetrics(w, y, dpi);
+        setGameMetrics(w, h, dpi);
         return await action();
     }
     finally {
@@ -26,7 +26,7 @@ export const openPaimonMenu = async () => {
     // 1.返回主界面
     await genshin.returnMainUi();
     // 2.打开派蒙菜单
-    await assertRegionAppearing(() => findTextWithinBounds("世界等级", 300, 230, 440, 100), "打开派蒙菜单超时", () => keyPress("ESCAPE"));
+    await assertRegionAppearing(() => findTextWithinBounds("生日", 300, 230, 440, 100), "打开派蒙菜单超时", () => keyPress("ESCAPE"));
 };
 /**
  * 打开游戏菜单（左侧按钮）

package/dist/mouse.d.ts

@@ -1,5 +1,7 @@
 type MouseWaypointsOptions = {
+    /** 是否按住鼠标左键拖动 */
     shouldDrag?: boolean;
+    /** 超时时间（毫秒，默认: 不超时） */
     timeout?: number;
 };
 /**
@@ -21,13 +23,13 @@ export declare const mouseMoveAlongWaypoints: (waypoints: {
  */
 export declare const mouseDrag: (x1: number, y1: number, x2: number, y2: number) => Promise<boolean>;
 type NaturalMouseMoveOptions = {
-    /** 移动持续时间（毫秒） */
+    /** 移动持续时间（毫秒，默认: 800） */
     duration: number;
-    /** 摆动幅度（像素） */
+    /** 摆动幅度（默认: 30） */
     wiggle?: number;
-    /** 随机种子 */
+    /** 随机种子（可选） */
     seed?: number;
-    /** 缓动函数 */
+    /** 缓动函数（默认: ease-out-cubic） */
     easing?: (progress: number) => number;
 };
 /** 贝塞尔曲线生成鼠标移动路径点 */

package/dist/ocr.d.ts

@@ -1,5 +1,5 @@
 import { RetryOptions } from "./workflow";
-type MatchDirection = "north" | "north-east" | "east" | "south-east" | "south" | "south-west" | "west" | "north-west";
+type MatchDirection = "north" /** 上半边 */ | "north-east" /** 右上四分之一 */ | "east" /** 右半边 */ | "south-east" /** 右下四分之一 */ | "south" /** 下半边 */ | "south-west" /** 左下四分之一 */ | "west" /** 左半边 */ | "north-west"; /** 左上四分之一 */
 /**
  * 在整个画面内搜索图片
  * @param path 图片路径
@@ -25,9 +25,9 @@ export declare const findImageWithinBounds: (path: string, x: number, y: number,
 export declare const findImageInDirection: (path: string, direction: MatchDirection) => Region | undefined;
 /** 文本搜索选项 */
 type TextMatchOptions = {
-    /** 是否忽略大小写（默认：是） */
+    /** 是否忽略大小写（默认: 是） */
     ignoreCase?: boolean;
-    /** 是否非完全匹配（默认：否） */
+    /** 是否非完全匹配（默认: 否） */
     contains?: boolean;
 };
 /**
@@ -64,11 +64,11 @@ export type ListView = {
     h: number;
     /** 列表项高度 */
     lineHeight: number;
-    /** 每次滚动的行数 */
+    /** 每次滚动的行数（默认: 1） */
     scrollLines?: number;
-    /** 横向内边距 */
+    /** 横向内边距 （默认: 10） */
     paddingX?: number;
-    /** 纵向内边距 */
+    /** 纵向内边距 （默认: 10） */
     paddingY?: number;
 };
 /**

package/dist/ocr.js

@@ -135,7 +135,7 @@ export const findTextWithinListView = async (text, listView, matchOptions, retry
                 return false;
             }
         }
-        // 异常情况：找不到任何文本
+        // 异常情况: 找不到任何文本
         return true;
     };
     const isTextFoundOrBottomReached = await waitForAction(() => findTargetText() != undefined || isReachedBottom(), async () => {

package/dist/workflow.d.ts

@@ -1,8 +1,8 @@
 export type Action = () => Promise<void> | void;
 export type RetryOptions = {
-    /** 重试次数 */
+    /** 重试次数（默认: 5） */
     maxAttempts?: number;
-    /** 重试间隔（毫秒） */
+    /** 重试间隔（毫秒，默认: 1000） */
     retryInterval?: number;
 };
 /**

package/dist/workflow.js

@@ -13,10 +13,12 @@ const defaultRetryInterval = 1000;
 export const waitForAction = async (condition, retryAction, options) => {
     const { maxAttempts = defaultMaxAttempts, retryInterval = defaultRetryInterval } = options || {};
     for (let i = 0; i < maxAttempts; i++) {
-        if (condition())
-            return true;
+        if (i === 0 && condition())
+            return true; // fast path
         await retryAction?.();
         await sleep(retryInterval);
+        if (condition())
+            return true;
     }
     return false;
 };

package/package.json

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

package/dist/flow.d.ts

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