@skrillex1224/playwright-toolkit 2.1.57 → 2.1.59

package/README.md

@@ -82,24 +82,23 @@ await Actor.exit();
 
 ### API 一览
 
-| 模块        | 方法                                                 | 说明                                   |
-| ----------- | ---------------------------------------------------- | -------------------------------------- |
-| `Launch`    | `getAdvancedLaunchOptions()`                         | 增强版启动参数                         |
-| `Launch`    | `getLaunchOptions()`                                 | 基础启动参数                           |
-| `Launch`    | `getFingerprintGeneratorOptions()`                   | 指纹生成器选项                         |
-| `AntiCheat` | `applyPage(page, options?)`                          | 应用时区/语言/权限/视口                |
-| `AntiCheat` | `applyContext(context, options?)`                    | 仅应用 Context 设置                    |
-| `AntiCheat` | `syncViewportWithScreen(page)`                       | 同步视口与屏幕                         |
-| `AntiCheat` | `getTlsFingerprintOptions(userAgent?)`               | got-scraping TLS 指纹                  |
-| `Humanize`  | `initializeCursor(page)`                             | 初始化 Cursor (必须先调用)             |
-| `Humanize`  | `jitterMs(base, jitterPercent?)`                     | 生成带抖动的毫秒数 (同步，返回 number) |
-| `Humanize`  | `humanType(page, selector, text, options?)`          | 人类化输入 (baseDelay=180ms ±40%)      |
-| `Humanize`  | `humanClick(page, selector, options?)`               | 人类化点击 (reactionDelay=250ms ±40%)  |
-| `Humanize`  | `warmUpBrowsing(page, baseDuration?)`                | 页面预热 (3500ms ±40%)                 |
-| `Humanize`  | `naturalScroll(page, direction?, distance?, steps?)` | 自然滚动 (带惯性+抖动)                 |
-| `Humanize`  | `simulateGaze(page, baseDurationMs?)`                | 模拟注视 (2500ms ±40%)                 |
-| `Humanize`  | `randomSleep(baseMs, jitterPercent?)`                | 随机延迟 (±30% 抖动)                   |
-| `Captcha`   | `useCaptchaMonitor(page, options)`                   | 验证码监控                             |
+| 模块        | 方法                                        | 说明                                   |
+| ----------- | ------------------------------------------- | -------------------------------------- |
+| `Launch`    | `getAdvancedLaunchOptions()`                | 增强版启动参数                         |
+| `Launch`    | `getLaunchOptions()`                        | 基础启动参数                           |
+| `Launch`    | `getFingerprintGeneratorOptions()`          | 指纹生成器选项                         |
+| `AntiCheat` | `applyPage(page, options?)`                 | 应用时区/语言/权限/视口                |
+| `AntiCheat` | `applyContext(context, options?)`           | 仅应用 Context 设置                    |
+| `AntiCheat` | `syncViewportWithScreen(page)`              | 同步视口与屏幕                         |
+| `AntiCheat` | `getTlsFingerprintOptions(userAgent?)`      | got-scraping TLS 指纹                  |
+| `Humanize`  | `initializeCursor(page)`                    | 初始化 Cursor (必须先调用)             |
+| `Humanize`  | `jitterMs(base, jitterPercent?)`            | 生成带抖动的毫秒数 (同步，返回 number) |
+| `Humanize`  | `humanType(page, selector, text, options?)` | 人类化输入 (baseDelay=180ms ±40%)      |
+| `Humanize`  | `humanClick(page, selector, options?)`      | 人类化点击 (reactionDelay=250ms ±40%)  |
+| `Humanize`  | `warmUpBrowsing(page, baseDuration?)`       | 页面预热 (3500ms ±40%)                 |
+| `Humanize`  | `simulateGaze(page, baseDurationMs?)`       | 模拟注视 (2500ms ±40%)                 |
+| `Humanize`  | `randomSleep(baseMs, jitterPercent?)`       | 随机延迟 (±30% 抖动)                   |
+| `Captcha`   | `useCaptchaMonitor(page, options)`          | 验证码监控                             |
 
 ---
 

package/dist/index.cjs

@@ -609,6 +609,17 @@ var Humanize = {
       throw error;
     }
   },
+  /**
+   * 渐进式滚动到元素可见（仅处理 Y 轴滚动）
+   * 返回 restore 方法，用于将滚动容器恢复到原位置
+   * 
+   * @param {import('playwright').Page} page
+   * @param {string|import('playwright').ElementHandle} target - CSS 选择器或元素句柄
+   * @param {Object} [options]
+   * @param {number} [options.maxSteps=25] - 最大滚动步数
+   * @param {number} [options.minStep=80] - 单次滚动最小步长
+   * @param {number} [options.maxStep=220] - 单次滚动最大步长
+   */
   /**
    * 渐进式滚动到元素可见（仅处理 Y 轴滚动）
    * 返回 restore 方法，用于将滚动容器恢复到原位置
@@ -623,7 +634,7 @@ var Humanize = {
   async humanScroll(page, target, options = {}) {
     const { maxSteps = 30, minStep = 150, maxStep = 400 } = options;
     const targetDesc = typeof target === "string" ? target : "ElementHandle";
-    logger5.debug(`humanScroll | \u76EE\u6807=${targetDesc}`);
+    logger5.info(`humanScroll | \u5F00\u59CB\u6EDA\u52A8\u76EE\u6807: ${targetDesc}`);
     let element;
     if (typeof target === "string") {
       element = await page.$(target);
@@ -636,23 +647,27 @@ var Humanize = {
     }
     const cursor = $GetCursor(page);
     let didScroll = false;
+    let lastRect = null;
+    let samePositionCount = 0;
     const checkVisibility = async () => {
       return await element.evaluate((el) => {
         const rect = el.getBoundingClientRect();
         if (!rect || rect.width === 0 || rect.height === 0) {
           return { code: "ZERO_DIMENSIONS", reason: "\u5C3A\u5BF8\u4E3A\u96F6" };
         }
-        const cx = rect.left + rect.width / 2;
-        const cy = rect.top + rect.height / 2;
         const viewH = window.innerHeight;
         const viewW = window.innerWidth;
+        const resultBase = { rect, viewH, viewW };
+        const cx = rect.left + rect.width / 2;
+        const cy = rect.top + rect.height / 2;
         if (cy < 0 || cy > viewH || cx < 0 || cx > viewW) {
           const direction = cy < 0 ? "up" : cy > viewH ? "down" : "unknown";
-          return { code: "OUT_OF_VIEWPORT", reason: "\u4E0D\u5728\u89C6\u53E3\u5185", direction, cy, viewH };
+          return { ...resultBase, code: "OUT_OF_VIEWPORT", reason: "\u4E0D\u5728\u89C6\u53E3\u5185", direction, cy };
         }
         const pointElement = document.elementFromPoint(cx, cy);
         if (pointElement && !el.contains(pointElement) && !pointElement.contains(el)) {
           return {
+            ...resultBase,
             code: "OBSTRUCTED",
             reason: "\u88AB\u906E\u6321",
             obstruction: {
@@ -660,24 +675,39 @@ var Humanize = {
               id: pointElement.id,
               className: pointElement.className
             },
-            cy,
-            // Return Center Y for smart direction calculation
-            viewH
+            cy
           };
         }
-        return { code: "VISIBLE" };
+        return { ...resultBase, code: "VISIBLE" };
       });
     };
     try {
       for (let i = 0; i < maxSteps; i++) {
         const status = await checkVisibility();
         if (status.code === "VISIBLE") {
-          logger5.debug("humanScroll | \u5143\u7D20\u53EF\u89C1\u4E14\u65E0\u906E\u6321");
+          logger5.info("humanScroll | \u5143\u7D20\u5DF2\u53EF\u89C1\u4E14\u65E0\u906E\u6321");
           return { element, didScroll };
         }
-        logger5.debug(`humanScroll | \u6B65\u9AA4 ${i + 1}/${maxSteps}: ${status.reason} ${status.direction ? `(${status.direction})` : ""}`);
+        const directionStr = status.direction ? `(${status.direction})` : "";
+        logger5.info(`humanScroll | \u6B65\u9AA4 ${i + 1}/${maxSteps}: ${status.reason} ${directionStr}`);
+        const currentRect = status.rect;
+        if (i > 0 && lastRect && currentRect) {
+          const dy = Math.abs(currentRect.top - lastRect.top);
+          const dx = Math.abs(currentRect.left - lastRect.left);
+          if (dy < 2 && dx < 2) {
+            samePositionCount++;
+            logger5.info(`humanScroll | \u26A0\uFE0F \u8B66\u544A: \u6EDA\u52A8\u540E\u4F4D\u7F6E\u672A\u53D8 (${samePositionCount}/3). dy=${dy}`);
+            if (samePositionCount >= 3) {
+              logger5.warn("humanScroll | \u26A0\uFE0F \u68C0\u6D4B\u5230\u65E0\u6548\u6EDA\u52A8 (\u5143\u7D20\u53EF\u80FD\u662F Fixed \u6216\u4F4D\u4E8E\u4E0D\u53EF\u6EDA\u52A8\u7684\u5BB9\u5668)\uFF0C\u5F3A\u5236\u505C\u6B62\uFF0C\u5C1D\u8BD5\u76F4\u63A5\u4EA4\u4E92");
+              return { element, didScroll };
+            }
+          } else {
+            samePositionCount = 0;
+          }
+        }
+        if (currentRect) lastRect = currentRect;
         if (status.code === "OBSTRUCTED" && status.obstruction) {
-          logger5.debug(`humanScroll | \u88AB\u4EE5\u4E0B\u5143\u7D20\u906E\u6321 <${status.obstruction.tag} id="${status.obstruction.id}">`);
+          logger5.info(`humanScroll | \u88AB\u906E\u6321: <${status.obstruction.tag}.${status.obstruction.className}>`);
         }
         let deltaY = 0;
         if (status.code === "OUT_OF_VIEWPORT") {
@@ -690,22 +720,23 @@ var Humanize = {
           }
         } else if (status.code === "OBSTRUCTED") {
           const isBottomHalf = status.cy > status.viewH / 2;
-          const direction = isBottomHalf ? 1 : -1;
-          deltaY = direction * (minStep + Math.random() * 50);
+          const dir = isBottomHalf ? 1 : -1;
+          deltaY = dir * (minStep + Math.random() * 50);
         }
         if (i === 0 || Math.random() < 0.2) {
           const viewSize = page.viewportSize();
           if (viewSize) {
             const safeX = viewSize.width * 0.5 + (Math.random() - 0.5) * 100;
             const safeY = viewSize.height * 0.5 + (Math.random() - 0.5) * 100;
-            await cursor.actions.move({ x: safeX, y: safeY });
+            await cursor.actions.move({ x: safeX, y: safeY }).catch(() => {
+            });
           }
         }
         await page.mouse.wheel(0, deltaY);
         didScroll = true;
-        await (0, import_delay2.default)(this.jitterMs(100 + Math.random() * 150, 0.2));
+        await (0, import_delay2.default)(this.jitterMs(150 + Math.random() * 100, 0.2));
       }
-      logger5.warn(`humanScroll | \u5728 ${maxSteps} \u6B65\u540E\u65E0\u6CD5\u786E\u4FDD\u53EF\u89C1\u6027`);
+      logger5.warn(`humanScroll | \u26A0\uFE0F \u8FBE\u5230\u6700\u5927\u6B65\u6570 (${maxSteps}) \u4ECD\u65E0\u6CD5\u5B8C\u5168\u53EF\u89C1\uFF0C\u653E\u5F03\u6EDA\u52A8`);
       return { element, didScroll };
     } catch (error) {
       logger5.fail("humanScroll", error);
@@ -917,34 +948,6 @@ var Humanize = {
       logger5.fail("warmUpBrowsing", error);
       throw error;
     }
-  },
-  /**
-   * 自然滚动 - 带惯性、减速效果和随机抖动
-   * @param {import('playwright').Page} page
-   * @param {'up' | 'down'} [direction='down'] - 滚动方向
-   * @param {number} [distance=300] - 总滚动距离基础值 (px)，±15% 抖动
-   * @param {number} [baseSteps=5] - 分几步完成基础值，±1 随机
-   */
-  async naturalScroll(page, direction = "down", distance = 300, baseSteps = 5) {
-    const steps = Math.max(3, baseSteps + Math.floor(Math.random() * 3) - 1);
-    const actualDistance = this.jitterMs(distance, 0.15);
-    logger5.start("naturalScroll", `dir=${direction}, dist=${actualDistance}, steps=${steps}`);
-    const sign = direction === "down" ? 1 : -1;
-    const stepDistance = actualDistance / steps;
-    try {
-      for (let i = 0; i < steps; i++) {
-        const factor = 1 - i / steps * 0.5;
-        const jitter = 0.9 + Math.random() * 0.2;
-        const scrollAmount = stepDistance * factor * sign * jitter;
-        await page.mouse.wheel(0, scrollAmount);
-        const baseDelay = 60 + i * 25;
-        await (0, import_delay2.default)(this.jitterMs(baseDelay, 0.3));
-      }
-      logger5.success("naturalScroll");
-    } catch (error) {
-      logger5.fail("naturalScroll", error);
-      throw error;
-    }
   }
 };