@bettergi/utils 0.1.0 → 0.1.2

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,9 +143,18 @@ 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}`);
 log.info(`POST 请求响应体内容${body2}`);
 ```
+
+### 日期时间
+
+```ts
+// 获取下一个（含当日）凌晨4点的时间
+const d1 = getNextDay4AM();
+// 获取下一个（含当日）周一凌晨4点的时间
+const d2 = getNextMonday4AM();
+```

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"));
 };
 /**
  * 打开游戏菜单（左侧按钮）
@@ -101,10 +101,11 @@ export const setTimeTo = async (hour, minute, options) => {
         .map(rad => ({ x: radius * Math.cos(rad), y: radius * Math.sin(rad) }))
         // 计算绝对坐标
         .map(p => ({ x: Math.round(p.x + centerX), y: Math.round(p.y + centerY) })));
-    // 3.拨动指针
+    // 3.调整时间
     await withGameMetrics(1920, 1080, 1.5, async () => {
+        // 拨动指针
         await mouseMoveAlongWaypoints(waypoints, { shouldDrag: true });
-        // 3.点击确认按钮，等待调整结束
+        // 点击确认按钮，等待调整结束
         await assertRegionAppearing(() => findTextInDirection("时间少于", "south-east", { contains: true }), "调整时间超时", () => {
             findTextInDirection("确认", "south-east")?.click();
         }, { maxAttempts: 20, retryInterval: 1000 });
@@ -120,12 +121,12 @@ export const setTimeTo = async (hour, minute, options) => {
 export const setTime = async (period, options) => {
     switch (period) {
         case "night":
-            return setTimeTo(0, 0, options);
+            return setTimeTo(0, 5, options);
         case "morning":
-            return setTimeTo(6, 0, options);
+            return setTimeTo(6, 5, options);
         case "noon":
-            return setTimeTo(12, 0, options);
+            return setTimeTo(12, 5, options);
         case "evening":
-            return setTimeTo(18, 0, options);
+            return setTimeTo(18, 5, options);
     }
 };

package/dist/index.d.ts

@@ -1,7 +1,16 @@
+/** 断言 */
 export * from "./asserts";
-export * from "./workflow";
+/** 游戏操作 */
 export * from "./game";
+/** HTTP 请求 */
 export * from "./http";
+/** 鼠标操作 */
 export * from "./mouse";
+/** 图像识别 */
 export * from "./ocr";
+/** 数据存储 */
 export * from "./store";
+/** 日期时间 */
+export * from "./time";
+/** 流程控制 */
+export * from "./workflow";

package/dist/index.js

@@ -1,7 +1,16 @@
+/** 断言 */
 export * from "./asserts";
-export * from "./workflow";
+/** 游戏操作 */
 export * from "./game";
+/** HTTP 请求 */
 export * from "./http";
+/** 鼠标操作 */
 export * from "./mouse";
+/** 图像识别 */
 export * from "./ocr";
+/** 数据存储 */
 export * from "./store";
+/** 日期时间 */
+export * from "./time";
+/** 流程控制 */
+export * from "./workflow";

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/time.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 获取下一个（含当日）凌晨4点的时间
+ */
+export declare const getNextDay4AM: () => Date;
+/**
+ * 获取下一个（含当日）周一凌晨4点的时间
+ */
+export declare const getNextMonday4AM: () => Date;

package/dist/time.js

@@ -0,0 +1,25 @@
+/**
+ * 获取下一个（含当日）凌晨4点的时间
+ */
+export const getNextDay4AM = () => {
+    const now = new Date();
+    const result = new Date(now);
+    result.setHours(4, 0, 0, 0);
+    // 如果当前时间在4点前，则返回今天4点，否则返回明天4点
+    const daysUntilNextDay = now.getHours() < 4 ? 0 : 1;
+    result.setDate(now.getDate() + daysUntilNextDay);
+    return result;
+};
+/**
+ * 获取下一个（含当日）周一凌晨4点的时间
+ */
+export const getNextMonday4AM = () => {
+    const now = new Date();
+    const result = new Date(now);
+    result.setHours(4, 0, 0, 0);
+    // 如果当前为周一且时间在4点前，则返回今天4点，否则返回下一个周一的4点
+    const currentDay = now.getDay();
+    const daysUntilNextMonday = currentDay === 1 && now.getHours() < 4 ? 0 : (8 - currentDay) % 7;
+    result.setDate(now.getDate() + daysUntilNextMonday);
+    return result;
+};

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.2",
   "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);
-};