@skrillex1224/playwright-toolkit 2.1.37 → 2.1.38

package/dist/index.cjs

@@ -357,6 +357,8 @@ var Utils = {
    * @param {import('playwright').Page} page - Playwright page 对象
    * @param {Object} [options] - 配置选项
    * @param {number} [options.buffer] - 额外缓冲高度 (默认: 视口高度的一半)
+   * @param {boolean} [options.restore] - 截图后是否恢复页面高度和样式 (默认: false)
+   * @param {number} [options.maxHeight] - 最大截图高度 (默认: 8000px)
    * @returns {Promise<string>} - base64 编码的 PNG 图片
    */
   async fullPageScreenshot(page, options = {}) {
@@ -364,15 +366,17 @@ var Utils = {
     const originalViewport = page.viewportSize();
     const defaultBuffer = Math.round((originalViewport?.height || 1080) / 2);
     const buffer = options.buffer ?? defaultBuffer;
+    const restore = options.restore ?? false;
+    const maxHeight = options.maxHeight ?? 8e3;
     try {
       const maxScrollHeight = await page.evaluate(() => {
-        let maxHeight = document.body.scrollHeight;
+        let maxHeight2 = document.body.scrollHeight;
         document.querySelectorAll("*").forEach((el) => {
           const style = window.getComputedStyle(el);
           const overflowY = style.overflowY;
           if ((overflowY === "auto" || overflowY === "scroll") && el.scrollHeight > el.clientHeight) {
-            if (el.scrollHeight > maxHeight) {
-              maxHeight = el.scrollHeight;
+            if (el.scrollHeight > maxHeight2) {
+              maxHeight2 = el.scrollHeight;
             }
             el.dataset.pkOrigOverflow = el.style.overflow;
             el.dataset.pkOrigHeight = el.style.height;
@@ -383,11 +387,12 @@ var Utils = {
             el.style.maxHeight = "none";
           }
         });
-        return maxHeight;
+        return maxHeight2;
       });
+      const targetHeight = Math.min(maxScrollHeight + buffer, maxHeight);
       await page.setViewportSize({
         width: originalViewport?.width || 1280,
-        height: maxScrollHeight + buffer
+        height: targetHeight
       });
       await (0, import_delay.default)(1e3);
       const buffer_ = await page.screenshot({
@@ -397,19 +402,21 @@ var Utils = {
       logger2.success("fullPageScreenshot", `captured ${Math.round(buffer_.length / 1024)} KB`);
       return buffer_.toString("base64");
     } finally {
-      await page.evaluate(() => {
-        document.querySelectorAll(".__pk_expanded__").forEach((el) => {
-          el.style.overflow = el.dataset.pkOrigOverflow || "";
-          el.style.height = el.dataset.pkOrigHeight || "";
-          el.style.maxHeight = el.dataset.pkOrigMaxHeight || "";
-          delete el.dataset.pkOrigOverflow;
-          delete el.dataset.pkOrigHeight;
-          delete el.dataset.pkOrigMaxHeight;
-          el.classList.remove("__pk_expanded__");
+      if (restore) {
+        await page.evaluate(() => {
+          document.querySelectorAll(".__pk_expanded__").forEach((el) => {
+            el.style.overflow = el.dataset.pkOrigOverflow || "";
+            el.style.height = el.dataset.pkOrigHeight || "";
+            el.style.maxHeight = el.dataset.pkOrigMaxHeight || "";
+            delete el.dataset.pkOrigOverflow;
+            delete el.dataset.pkOrigHeight;
+            delete el.dataset.pkOrigMaxHeight;
+            el.classList.remove("__pk_expanded__");
+          });
         });
-      });
-      if (originalViewport) {
-        await page.setViewportSize(originalViewport);
+        if (originalViewport) {
+          await page.setViewportSize(originalViewport);
+        }
       }
     }
   }
@@ -1532,6 +1539,181 @@ function isIgnorableError(error) {
   return msg.includes("already handled") || msg.includes("Target closed") || msg.includes("closed");
 }
 
+// src/mutation.js
+var import_uuid2 = require("uuid");
+var logger9 = createLogger("Mutation");
+function generateKey(prefix) {
+  return `__${prefix}_${(0, import_uuid2.v4)().replace(/-/g, "_")}`;
+}
+var Mutation = {
+  /**
+   * 等待 DOM 元素稳定（无变化）
+   * 使用 MutationObserver 监控指定元素，当元素持续一段时间无变化时 resolve
+   * 
+   * @param {import('playwright').Page} page - Playwright page 对象
+   * @param {string | string[]} selectors - 要监控的 CSS 选择器，单个或多个
+   * @param {Object} [options] - 配置选项
+   * @param {number} [options.stableTime] - 无变化持续时间后 resolve (毫秒, 默认: 5000)
+   * @param {number} [options.timeout] - 整体超时时间 (毫秒, 默认: 60000)
+   * @param {Function} [options.onMutation] - 变化时的回调钩子 (mutationCount: number) => void
+   * @returns {Promise<{ mutationCount: number, stableTime: number }>} - 返回变化次数和稳定时长
+   */
+  async waitForStable(page, selectors, options = {}) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    const stableTime = options.stableTime ?? 5e3;
+    const timeout = options.timeout ?? 6e4;
+    const onMutation = options.onMutation;
+    logger9.start("waitForStable", `\u76D1\u63A7 ${selectorList.length} \u4E2A\u9009\u62E9\u5668, \u7A33\u5B9A\u65F6\u95F4=${stableTime}ms`);
+    const eventName = generateKey("pk_mut_evt");
+    const callbackName = generateKey("pk_mut_cb");
+    if (onMutation) {
+      try {
+        await page.exposeFunction(callbackName, (count) => {
+          try {
+            onMutation(count);
+          } catch (e) {
+          }
+        });
+      } catch (e) {
+      }
+    }
+    const result = await page.evaluate(
+      async ({ selectorList: selectorList2, stableTime: stableTime2, timeout: timeout2, eventName: eventName2, callbackName: callbackName2, hasCallback }) => {
+        return new Promise((resolve, reject) => {
+          let mutationCount = 0;
+          let stableTimer = null;
+          let timeoutTimer = null;
+          const observers = [];
+          const cleanup = () => {
+            observers.forEach((obs) => obs.disconnect());
+            if (stableTimer) clearTimeout(stableTimer);
+            if (timeoutTimer) clearTimeout(timeoutTimer);
+          };
+          const resetStableTimer = () => {
+            if (stableTimer) clearTimeout(stableTimer);
+            stableTimer = setTimeout(() => {
+              cleanup();
+              resolve({ mutationCount, stableTime: stableTime2 });
+            }, stableTime2);
+          };
+          timeoutTimer = setTimeout(() => {
+            cleanup();
+            reject(new Error(`waitForStable \u8D85\u65F6 (${timeout2}ms), \u5DF2\u68C0\u6D4B\u5230 ${mutationCount} \u6B21\u53D8\u5316`));
+          }, timeout2);
+          selectorList2.forEach((selector) => {
+            const elements = document.querySelectorAll(selector);
+            elements.forEach((element) => {
+              const observer = new MutationObserver((mutations) => {
+                mutationCount += mutations.length;
+                if (hasCallback && window[callbackName2]) {
+                  window[callbackName2](mutationCount);
+                }
+                resetStableTimer();
+              });
+              observer.observe(element, {
+                childList: true,
+                subtree: true,
+                characterData: true,
+                attributes: true
+              });
+              observers.push(observer);
+            });
+          });
+          if (observers.length === 0) {
+            cleanup();
+            resolve({ mutationCount: 0, stableTime: 0 });
+            return;
+          }
+          resetStableTimer();
+        });
+      },
+      { selectorList, stableTime, timeout, eventName, callbackName, hasCallback: !!onMutation }
+    );
+    logger9.success("waitForStable", `DOM \u7A33\u5B9A, \u603B\u5171 ${result.mutationCount} \u6B21\u53D8\u5316`);
+    return result;
+  },
+  /**
+   * 创建一个持续监控 DOM 变化的监控器
+   * 
+   * @param {import('playwright').Page} page - Playwright page 对象
+   * @param {string | string[]} selectors - 要监控的 CSS 选择器
+   * @param {Object} [options] - 配置选项
+   * @param {Function} [options.onMutation] - 变化时的回调 (mutationCount: number) => void
+   * @returns {Promise<{ stop: () => Promise<{ totalMutations: number }> }>} - 返回停止函数
+   */
+  async createMonitor(page, selectors, options = {}) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    const onMutation = options.onMutation;
+    logger9.start("createMonitor", `\u76D1\u63A7 ${selectorList.length} \u4E2A\u9009\u62E9\u5668`);
+    const monitorKey = generateKey("pk_mon");
+    const callbackName = generateKey("pk_mon_cb");
+    const cleanerName = generateKey("pk_mon_clean");
+    if (onMutation) {
+      try {
+        await page.exposeFunction(callbackName, (count) => {
+          try {
+            onMutation(count);
+          } catch (e) {
+          }
+        });
+      } catch (e) {
+      }
+    }
+    await page.evaluate(({ selectorList: selectorList2, monitorKey: monitorKey2, callbackName: callbackName2, cleanerName: cleanerName2, hasCallback }) => {
+      const monitor = {
+        observers: [],
+        totalMutations: 0,
+        running: true
+      };
+      selectorList2.forEach((selector) => {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach((element) => {
+          const observer = new MutationObserver((mutations) => {
+            if (!monitor.running) return;
+            monitor.totalMutations += mutations.length;
+            if (hasCallback && window[callbackName2]) {
+              window[callbackName2](monitor.totalMutations);
+            }
+          });
+          observer.observe(element, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributes: true
+          });
+          monitor.observers.push(observer);
+        });
+      });
+      window[monitorKey2] = monitor;
+      window[cleanerName2] = () => {
+        monitor.running = false;
+        monitor.observers.forEach((obs) => obs.disconnect());
+        const total = monitor.totalMutations;
+        delete window[monitorKey2];
+        delete window[cleanerName2];
+        return total;
+      };
+    }, { selectorList, monitorKey, callbackName, cleanerName, hasCallback: !!onMutation });
+    logger9.success("createMonitor", "\u76D1\u63A7\u5668\u5DF2\u542F\u52A8");
+    return {
+      stop: async () => {
+        let totalMutations = 0;
+        try {
+          totalMutations = await page.evaluate((cleanerName2) => {
+            if (window[cleanerName2]) {
+              return window[cleanerName2]();
+            }
+            return 0;
+          }, cleanerName);
+        } catch (e) {
+        }
+        logger9.success("createMonitor.stop", `\u76D1\u63A7\u5DF2\u505C\u6B62, \u5171 ${totalMutations} \u6B21\u53D8\u5316`);
+        return { totalMutations };
+      }
+    };
+  }
+};
+
 // index.js
 var usePlaywrightToolKit = () => {
   return {
@@ -1545,7 +1727,8 @@ var usePlaywrightToolKit = () => {
     Captcha,
     Sse,
     Errors: errors_exports,
-    Interception
+    Interception,
+    Mutation
   };
 };
 // Annotate the CommonJS export names for ESM import in node: