@weapp-vite/miniprogram-automator 1.2.12 → 1.2.14

package/README.md

@@ -107,6 +107,25 @@ await button?.tap()
 await page.waitFor(500)
 ```
 
+### 4.5 App-Service 降级（route fallback）能力边界
+
+部分 DevTools 版本（如 `2.01.2510290`）的 page-frame 定向协议失效，表现为 `Page.*` RPC 全部超时。此时本库自动切换到 App-Service 降级通道（`App.callFunction` + `wx.createSelectorQuery`），无需任何配置。
+
+降级模式下各能力可用性：
+
+| 能力                                                      | 状态        | 说明                                                                                           |
+| --------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
+| `page.$` / `page.$$`                                      | ✅          | 经 route 查询返回降级元素                                                                      |
+| `page.data()` / `page.setData()` / `page.callMethod()`    | ✅          | 经 App-Service 读写页面数据、调用页面方法                                                      |
+| `element.offset()` / `element.size()` / `element.style()` | ✅          | 实时经 `createSelectorQuery` 读取 rect 与 computedStyle（每次读取都重新查询，不缓存）          |
+| `element.attribute('id')` / `element.attribute('data-*')` | ✅          | 经快照读取 id 与 dataset                                                                       |
+| `element.$()` / `element.$$()`                            | ❌ 明确报错 | 元素级查询依赖 page-frame 协议；请改用 `page.$()` / `page.$$()`                                |
+| `element.text()`                                          | ❌ 明确报错 | `SelectorQuery` 无法读取 `innerText`；请改用 `page.data()` 或 `page.callMethod()` 断言文案来源 |
+| `element.tap()` / `trigger()` 等真实交互                  | ❌ 明确报错 | AppService 无法合成真实触摸事件；请改用 `page.callMethod()` 或 `evaluate` 间接触发页面逻辑     |
+| `scroll-view` 容器滚动                                    | ❌          | 需 page-frame 协议支持，降级模式不可用                                                         |
+
+> 降级元素上的不支持操作会**立即抛出带替代建议的错误**，不会再像旧版那样挂起 30s 才超时。
+
 ## 5. 主要导出
 
 | 导出                      | 说明                                     |

package/dist/index.d.mts

@@ -94,6 +94,12 @@ interface IElementOptions {
   videoId?: string;
   pageId: number;
   routeFallback?: boolean;
+  /** route 降级元素的定位信息:用于只读方法经 App-service 实时重查快照。 */
+  routeFallbackSelector?: string;
+  routeFallbackIndex?: number;
+  routeFallbackRoute?: string;
+  routeFallbackQuery?: Record<string, any>;
+  routeFallbackScopeSelectors?: string[];
   tagName: string;
 }
 /** ITouch 的类型定义。 */
@@ -123,7 +129,7 @@ interface ElementQueryOptions {
 }
 /** Element 的实现。 */
 declare class Element {
-  private connection;
+  protected readonly connection: Connection;
   private elementMap;
   tagName: string;
   protected nodeId: string | null;

package/dist/index.mjs

@@ -222,6 +222,223 @@ function toStr(value) {
 	return value == null ? "" : String(value);
 }
 //#endregion
+//#region src/pageRouteSnapshot.ts
+const ROUTE_ELEMENT_SNAPSHOT_TIMEOUT = 5e3;
+const ROUTE_ELEMENT_SNAPSHOT_EMPTY_RETRIES = 2;
+const ROUTE_ELEMENT_SNAPSHOT_RETRY_DELAY = 220;
+/**
+* 页面定位 + 组件作用域遍历逻辑与 Page.renderedNodes 保持一致:
+* 先按 route/query 找到目标页面,再逐层进入自定义组件作用域查询,
+* 返回首个命中作用域里 selectAll(selector)[index] 的快照;未命中返回 null。
+*/
+const ROUTE_ELEMENT_SNAPSHOT_FUNCTION_DECLARATION = `function (route, query, selector, index, scopeSelectors, styleNames) {
+  function normalizeRoute(value) {
+    return String(value || '').replace(/^\\/+/, '').replace(/\\/+$/g, '');
+  }
+  function matchesQuery(page, expectedQuery) {
+    if (!expectedQuery || !Object.keys(expectedQuery).length) {
+      return true;
+    }
+    var actualQuery = page && (page.options || page.query || {});
+    return Object.keys(expectedQuery).every(function (key) {
+      var actualValue = String(actualQuery[key] == null ? '' : actualQuery[key]);
+      var expectedValue = String(expectedQuery[key]);
+      var decodedActualValue = actualValue;
+      try {
+        decodedActualValue = decodeURIComponent(actualValue);
+      }
+      catch (_) {
+      }
+      return actualValue === expectedValue
+        || decodedActualValue === expectedValue
+        || actualValue === encodeURIComponent(expectedValue);
+    });
+  }
+  var pages = typeof getCurrentPages === 'function' ? getCurrentPages() : [];
+  var expectedRoute = normalizeRoute(route);
+  var page = null;
+  for (var pageIndex = pages.length - 1; pageIndex >= 0; pageIndex -= 1) {
+    var candidate = pages[pageIndex];
+    var candidateRoute = normalizeRoute(candidate && (candidate.path || candidate.route || candidate.__route__));
+    if ((!expectedRoute || candidateRoute === expectedRoute) && matchesQuery(candidate, query)) {
+      page = candidate;
+      break;
+    }
+  }
+  if (!page) {
+    return null;
+  }
+  function createSelectorQuery(scope) {
+    var selectorQuery = null;
+    var createdFromScope = false;
+    if (scope && typeof scope.createSelectorQuery === 'function') {
+      selectorQuery = scope.createSelectorQuery();
+      createdFromScope = true;
+    }
+    else if (typeof wx !== 'undefined' && wx && typeof wx.createSelectorQuery === 'function') {
+      selectorQuery = wx.createSelectorQuery();
+    }
+    else if (typeof page.createSelectorQuery === 'function') {
+      selectorQuery = page.createSelectorQuery();
+    }
+    if (!selectorQuery) {
+      return null;
+    }
+    if (!createdFromScope && typeof selectorQuery.in === 'function') {
+      try {
+        selectorQuery = selectorQuery.in(scope || page);
+      }
+      catch (_) {
+      }
+    }
+    return selectorQuery;
+  }
+  function pushUnique(list, seen, item) {
+    if (!item) {
+      return;
+    }
+    var id = item.is || item.id || item.__wxWebviewId__ || item.__wxExparserNodeId__ || String(list.length);
+    if (seen[id]) {
+      return;
+    }
+    seen[id] = true;
+    list.push(item);
+  }
+  function collectScopes(root, scopeSelectors) {
+    var scopes = [];
+    var seen = {};
+    var queue = [];
+    pushUnique(scopes, seen, root);
+    queue.push(root);
+    for (var queueIndex = 0; queueIndex < queue.length && queueIndex < 60; queueIndex += 1) {
+      var scope = queue[queueIndex];
+      if (!scope || typeof scope.selectAllComponents !== 'function') {
+        continue;
+      }
+      var children = [];
+      var componentSelectors = Array.isArray(scopeSelectors) ? scopeSelectors.slice() : [];
+      componentSelectors.push(selector, '*', 'weapp-app-shell', 'weapp-layout-default');
+      for (var selectorIndex = 0; selectorIndex < componentSelectors.length; selectorIndex += 1) {
+        if (!componentSelectors[selectorIndex]) {
+          continue;
+        }
+        try {
+          var selected = scope.selectAllComponents(componentSelectors[selectorIndex]);
+          if (Array.isArray(selected)) {
+            children = children.concat(selected);
+          }
+        }
+        catch (_) {
+        }
+      }
+      for (var childIndex = 0; childIndex < children.length; childIndex += 1) {
+        var child = children[childIndex];
+        var previousLength = scopes.length;
+        pushUnique(scopes, seen, child);
+        if (scopes.length > previousLength) {
+          queue.push(child);
+        }
+      }
+    }
+    return scopes;
+  }
+  function queryScope(scope) {
+    return new Promise(function (resolve) {
+      var settled = false;
+      var timer = setTimeout(function () {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        resolve([]);
+      }, 800);
+      function finish(nodes) {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        resolve(Array.isArray(nodes) ? nodes : nodes ? [nodes] : []);
+      }
+      try {
+        var selectorQuery = createSelectorQuery(scope);
+        if (!selectorQuery) {
+          finish([]);
+          return;
+        }
+        selectorQuery
+          .selectAll(selector)
+          .fields({
+            id: true,
+            dataset: true,
+            rect: true,
+            size: true,
+            computedStyle: Array.isArray(styleNames) ? styleNames : []
+          }, function (nodes) {
+            finish(nodes);
+          })
+          .exec();
+      }
+      catch (_) {
+        finish([]);
+      }
+    });
+  }
+  return new Promise(function (resolve) {
+    try {
+      var scopes = collectScopes(page, scopeSelectors);
+      var scopeIndex = 0;
+      function next() {
+        if (scopeIndex >= scopes.length) {
+          resolve(null);
+          return;
+        }
+        var scope = scopes[scopeIndex];
+        scopeIndex += 1;
+        queryScope(scope).then(function (nodes) {
+          if (nodes.length > 0) {
+            resolve(nodes[index] || null);
+            return;
+          }
+          next();
+        }, function () {
+          next();
+        });
+      }
+      next();
+    }
+    catch (_) {
+      resolve(null);
+    }
+  });
+}`;
+/**
+* 读取降级元素快照。未找到(页面不在/选择器无命中/索引越界)返回 null,
+* 由调用方决定抛错文案;永不因为协议失效而长时间挂起。
+*/
+async function readRouteElementSnapshot(connection, route, query, selector, index, scopeSelectors = [], styleNames = [], timeout = ROUTE_ELEMENT_SNAPSHOT_TIMEOUT) {
+	const startedAt = Date.now();
+	for (let attempt = 0; attempt <= ROUTE_ELEMENT_SNAPSHOT_EMPTY_RETRIES; attempt += 1) {
+		const remaining = attempt === 0 ? timeout : Math.max(1, timeout - (Date.now() - startedAt));
+		const { result } = await connection.send("App.callFunction", {
+			functionDeclaration: ROUTE_ELEMENT_SNAPSHOT_FUNCTION_DECLARATION,
+			args: [
+				route,
+				query,
+				selector,
+				index,
+				scopeSelectors,
+				styleNames
+			]
+		}, { timeout: remaining });
+		if (result != null || attempt === ROUTE_ELEMENT_SNAPSHOT_EMPTY_RETRIES) return result ?? null;
+		const retryRemaining = timeout - (Date.now() - startedAt);
+		if (retryRemaining <= 0) break;
+		await sleep$1(Math.min(ROUTE_ELEMENT_SNAPSHOT_RETRY_DELAY, retryRemaining));
+	}
+	return null;
+}
+//#endregion
 //#region src/Element.ts
 const ELEMENT_QUERY_TIMEOUT = 2500;
 const ELEMENT_WXML_TIMEOUT = 8e3;
@@ -272,7 +489,17 @@ var Element = class Element {
 		};
 	}
 	async offset() {
-		return await this.send("Element.getOffset");
+		const offset = await this.send("Element.getOffset");
+		if (offset?.width !== void 0 && offset.height !== void 0) return offset;
+		try {
+			const dimensions = await this.size();
+			return {
+				...offset,
+				...dimensions
+			};
+		} catch {
+			return offset;
+		}
 	}
 	async text() {
 		return await this.domProperty("innerText");
@@ -394,8 +621,87 @@ var Element = class Element {
 };
 /** App-Service 路由降级元素仅用于只读查询，不能伪装成交互协议元素。 */
 var RouteFallbackElement = class extends Element {
+	routeSelector;
+	routeIndex;
+	routeRoute;
+	routeQuery;
+	routeScopeSelectors;
+	constructor(connection, options, elementMap) {
+		super(connection, options, elementMap);
+		this.routeSelector = options.routeFallbackSelector;
+		this.routeIndex = options.routeFallbackIndex;
+		this.routeRoute = options.routeFallbackRoute;
+		this.routeQuery = options.routeFallbackQuery;
+		this.routeScopeSelectors = options.routeFallbackScopeSelectors ?? [];
+	}
+	/**
+	* 经 App-service SelectorQuery 实时重查元素快照(rect/size/dataset/computedStyle)。
+	* 每次读取都重新查询,保证滚动/重渲染后拿到的是当前值;未命中返回 null。
+	*/
+	async readSnapshot(styleNames = []) {
+		if (!this.routeSelector || this.routeIndex === void 0 || !this.routeRoute) return null;
+		return await readRouteElementSnapshot(this.connection, this.routeRoute, this.routeQuery ?? {}, this.routeSelector, this.routeIndex, this.routeScopeSelectors, styleNames);
+	}
+	missingSnapshot(what) {
+		return /* @__PURE__ */ new Error(`route fallback 元素未取到${what}: ${this.routeSelector ?? "(未知选择器)"}(页面已切换或元素已卸载)`);
+	}
+	async $(selector, _options = {}) {
+		return this.unsupported(`Element.$(${selector})`);
+	}
+	async $$(selector, _options = {}) {
+		return this.unsupported(`Element.$$(${selector})`);
+	}
+	async offset() {
+		const snapshot = await this.readSnapshot();
+		if (snapshot?.left === void 0 || snapshot.top === void 0) throw this.missingSnapshot("坐标");
+		return {
+			left: snapshot.left,
+			top: snapshot.top,
+			width: snapshot.width,
+			height: snapshot.height
+		};
+	}
+	async size() {
+		const snapshot = await this.readSnapshot();
+		if (snapshot?.width === void 0 || snapshot.height === void 0) throw this.missingSnapshot("尺寸");
+		return {
+			width: snapshot.width,
+			height: snapshot.height
+		};
+	}
+	async style(name) {
+		if (!isStr(name)) throw new Error("name must be a string");
+		const value = (await this.readSnapshot([name]))?.[name];
+		if (value === void 0) throw this.missingSnapshot(`样式 ${name}`);
+		return value;
+	}
+	async attribute(name) {
+		if (!isStr(name)) throw new Error("name must be a string");
+		const snapshot = await this.readSnapshot();
+		if (name === "id") return snapshot?.id;
+		if (name.startsWith("data-")) {
+			const key = name.slice(5).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+			return snapshot?.dataset?.[key];
+		}
+		throw new Error(`route fallback 元素仅支持读取 id 与 data-* 属性,不支持 attribute(${name})`);
+	}
 	unsupported(method) {
-		throw new Error(`App-Service route fallback 元素不支持 ${method}`);
+		throw new Error(`App-Service route fallback 元素不支持 ${method}(真实交互依赖已失效的 page-frame 协议);可改用 page.callMethod()/evaluate 间接触发页面逻辑`);
+	}
+	async text() {
+		throw new Error("App-Service route fallback 元素不支持 text(SelectorQuery 无法读取 innerText);请改用 page.data() 断言数据源,或 page.callMethod()/evaluate 读取");
+	}
+	async value() {
+		this.unsupported("Element.value");
+	}
+	async property(name) {
+		this.unsupported(`Element.property(${name})`);
+	}
+	async wxml() {
+		this.unsupported("Element.wxml");
+	}
+	async outerWxml() {
+		this.unsupported("Element.outerWxml");
 	}
 	async tap() {
 		this.unsupported("Element.tap");
@@ -640,7 +946,7 @@ var Connection = class Connection extends EventEmitter {
 //#endregion
 //#region src/headless.ts
 async function launchHeadlessAutomator(options) {
-	return await (await import("./launch-BFWwqoyn.mjs")).launch({ projectPath: options.projectPath });
+	return await (await import("./launch-DKcPk1N2.mjs")).launch({ projectPath: options.projectPath });
 }
 //#endregion
 //#region src/launcher/portLease.ts
@@ -739,7 +1045,7 @@ async function acquireAutomatorPortLease(preferredPort) {
 }
 //#endregion
 //#region package.json
-var version = "1.2.12";
+var version = "1.2.14";
 //#endregion
 //#region src/Native.ts
 /** Native 的实现。 */
@@ -800,14 +1106,19 @@ function resolveFallbackTagName(selector) {
 	return "view";
 }
 /** 将 App-Service 查询到的渲染节点包装为 Element 兼容对象。 */
-function createRouteFallbackElement(connection, elementMap, pageId, selector, node, index) {
+function createRouteFallbackElement(connection, elementMap, pageId, selector, node, index, route, query, scopeSelectors = []) {
 	const nodeId = typeof node.id === "string" && node.id ? normalizeFallbackIdPart(node.id) : String(index);
 	const elementId = `__weapp_vite_route_fallback_${pageId}_${normalizeFallbackIdPart(selector)}_${nodeId}_${index}`;
 	return Element.create(connection, {
 		elementId,
 		pageId,
 		routeFallback: true,
-		tagName: resolveFallbackTagName(selector)
+		tagName: resolveFallbackTagName(selector),
+		routeFallbackSelector: selector,
+		routeFallbackIndex: index,
+		routeFallbackRoute: route,
+		routeFallbackQuery: query,
+		routeFallbackScopeSelectors: [...scopeSelectors]
 	}, elementMap);
 }
 //#endregion
@@ -976,6 +1287,7 @@ const PAGE_CALL_METHOD_FALLBACK_RETRY_DELAY = 300;
 const PAGE_RENDERED_TIMEOUT = 15e3;
 const PAGE_RENDERED_POLL_DELAY = 220;
 const PAGE_RENDERED_QUERY_TIMEOUT = 5e3;
+const PAGE_RENDERED_EMPTY_RETRIES = 2;
 const PAGE_ROOT_SELECTORS = [
 	"page",
 	"body",
@@ -1723,10 +2035,21 @@ var Page = class Page {
 		return (await this.queryRouteElements(selector, options))[0] ?? null;
 	}
 	async queryRouteElements(selector, options) {
-		return (await this.renderedNodes(selector, {
-			componentSelectors: options.componentSelectors,
-			timeout: options.timeout ?? PAGE_QUERY_TIMEOUT
-		})).map((node, index) => createRouteFallbackElement(this.connection, this.elementMap, this.id, selector, node, index));
+		const timeout = options.timeout ?? PAGE_QUERY_TIMEOUT;
+		const startedAt = Date.now();
+		let nodes = [];
+		for (let attempt = 0; attempt <= PAGE_RENDERED_EMPTY_RETRIES; attempt += 1) {
+			const requestTimeout = attempt === 0 ? timeout : Math.max(1, timeout - (Date.now() - startedAt));
+			nodes = await this.renderedNodes(selector, {
+				componentSelectors: options.componentSelectors,
+				timeout: requestTimeout
+			});
+			if (nodes.length > 0 || attempt === PAGE_RENDERED_EMPTY_RETRIES) break;
+			const remaining = timeout - (Date.now() - startedAt);
+			if (remaining <= 0) break;
+			await sleep$1(Math.min(PAGE_RENDERED_POLL_DELAY, remaining));
+		}
+		return nodes.map((node, index) => createRouteFallbackElement(this.connection, this.elementMap, this.id, selector, node, index, this.path, this.query, options.componentSelectors));
 	}
 	async callRouteMethod(method, args, timeout = PAGE_CALL_METHOD_TIMEOUT) {
 		return await callRouteMethodViaAppService(this.connection, this.path, this.query, method, args, timeout);
@@ -2142,6 +2465,7 @@ var MiniProgram = class extends EventEmitter {
 		const toolInfo = await this.send("Tool.getInfo");
 		this.connection.configureToolInfo(toolInfo);
 		const sdkVersion = toolInfo.SDKVersion;
+		if (typeof sdkVersion !== "string" || !sdkVersion.trim()) return;
 		if (sdkVersion !== "dev" && cmpVersion(sdkVersion, "2.7.3") < 0) throw new Error(`SDKVersion is currently ${sdkVersion}, while automator(${version}) requires at least version 2.7.3`);
 	}
 	/**