assistsx-js 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "assistsx-js",
-    "version": "0.2.1",
+    "version": "0.2.2",
     "description": "assistsx-js自动化开发SDK",
     "main": "dist/index.cjs",
     "module": "dist/index.js",

package/src/assistsx-async.ts

@@ -9,6 +9,7 @@ import { Bounds } from "./bounds";
 import { generateUUID } from "./utils";
 import { AppInfo } from "./app-info";
 import { DeviceInfo } from "./device-info";
+import type { NodeLookupScope } from "./node-lookup-scope";
 import {
     AssistsX,
     callbacks,
@@ -156,15 +157,23 @@ export class AssistsXAsync {
         filterDes,
         filterText,
         timeout,
+        scope,
     }: {
         filterClass?: string;
         filterViewId?: string;
         filterDes?: string;
         filterText?: string;
         timeout?: number;
+        scope?: NodeLookupScope;
     } = {}): Promise<Node[]> {
         const response = await this.asyncCall(CallMethod.getAllNodes, {
-            args: { filterClass, filterViewId, filterDes, filterText },
+            args: {
+                filterClass,
+                filterViewId,
+                filterDes,
+                filterText,
+                ...(scope !== undefined ? { scope } : {}),
+            },
             timeout,
         });
         const data = response.getDataOrDefault([]);
@@ -448,10 +457,27 @@ export class AssistsXAsync {
     /**
      * 获取当前应用包名
      * @param timeout 超时时间(秒)，默认30秒
-     * @returns 包名
      */
-    public static async getPackageName(timeout?: number): Promise<string> {
+    public static async getPackageName(timeout?: number): Promise<string>;
+    /**
+     * 获取当前应用包名
+     * @param options.timeout 超时时间(秒)，默认30秒
+     * @param options.scope 节点查找范围（可选）
+     */
+    public static async getPackageName(options: {
+        timeout?: number;
+        scope?: NodeLookupScope;
+    }): Promise<string>;
+    public static async getPackageName(
+        timeoutOrOptions?: number | { timeout?: number; scope?: NodeLookupScope }
+    ): Promise<string> {
+        const normalized =
+            typeof timeoutOrOptions === "number"
+                ? { timeout: timeoutOrOptions as number }
+                : (timeoutOrOptions ?? {});
+        const { timeout, scope } = normalized;
         const response = await this.asyncCall(CallMethod.getPackageName, {
+            args: scope !== undefined ? { scope } : undefined,
             timeout,
         });
         return response.getDataOrDefault("");
@@ -494,16 +520,24 @@ export class AssistsXAsync {
             filterDes,
             node,
             timeout,
+            scope,
         }: {
             filterClass?: string;
             filterText?: string;
             filterDes?: string;
             node?: Node;
             timeout?: number;
+            scope?: NodeLookupScope;
         } = {}
     ): Promise<Node[]> {
         const response = await this.asyncCall(CallMethod.findById, {
-            args: { id, filterClass, filterText, filterDes },
+            args: {
+                id,
+                filterClass,
+                filterText,
+                filterDes,
+                ...(scope !== undefined ? { scope } : {}),
+            },
             node,
             timeout,
         });
@@ -535,16 +569,24 @@ export class AssistsXAsync {
             filterDes,
             node,
             timeout,
+            scope,
         }: {
             filterClass?: string;
             filterViewId?: string;
             filterDes?: string;
             node?: Node;
             timeout?: number;
+            scope?: NodeLookupScope;
         } = {}
     ): Promise<Node[]> {
         const response = await this.asyncCall(CallMethod.findByText, {
-            args: { text, filterClass, filterViewId, filterDes },
+            args: {
+                text,
+                filterClass,
+                filterViewId,
+                filterDes,
+                ...(scope !== undefined ? { scope } : {}),
+            },
             node,
             timeout,
         });
@@ -576,16 +618,24 @@ export class AssistsXAsync {
             filterDes,
             node,
             timeout,
+            scope,
         }: {
             filterText?: string;
             filterViewId?: string;
             filterDes?: string;
             node?: Node;
             timeout?: number;
+            scope?: NodeLookupScope;
         } = {}
     ): Promise<Node[]> {
         const response = await this.asyncCall(CallMethod.findByTags, {
-            args: { className, filterText, filterViewId, filterDes },
+            args: {
+                className,
+                filterText,
+                filterViewId,
+                filterDes,
+                ...(scope !== undefined ? { scope } : {}),
+            },
             node,
             timeout,
         });
@@ -603,14 +653,35 @@ export class AssistsXAsync {
      * 查找所有匹配文本的节点
      * @param text 要查找的文本
      * @param timeout 超时时间(秒)，默认30秒
-     * @returns 节点数组
      */
     public static async findByTextAllMatch(
         text: string,
         timeout?: number
+    ): Promise<Node[]>;
+    /**
+     * 查找所有匹配文本的节点
+     * @param text 要查找的文本
+     * @param options.timeout 超时时间(秒)，默认30秒
+     * @param options.scope 节点查找范围（可选）
+     */
+    public static async findByTextAllMatch(
+        text: string,
+        options: { timeout?: number; scope?: NodeLookupScope }
+    ): Promise<Node[]>;
+    public static async findByTextAllMatch(
+        text: string,
+        timeoutOrOptions?: number | { timeout?: number; scope?: NodeLookupScope }
     ): Promise<Node[]> {
+        const normalized =
+            typeof timeoutOrOptions === "number"
+                ? { timeout: timeoutOrOptions as number }
+                : (timeoutOrOptions ?? {});
+        const { timeout, scope } = normalized;
         const response = await this.asyncCall(CallMethod.findByTextAllMatch, {
-            args: { text },
+            args: {
+                text,
+                ...(scope !== undefined ? { scope } : {}),
+            },
             timeout,
         });
         const data = response.getDataOrDefault([]);
@@ -1276,6 +1347,7 @@ export class AssistsXAsync {
      * @param options.filePath 文件路径（可选，不提供则自动生成）
      * @param options.prettyPrint 是否格式化输出，默认为 true
      * @param options.timeout 超时时间(秒)，默认30秒
+     * @param options.scope 节点查找范围（可选）
      * @returns 保存的文件路径
      */
     public static async saveRootNodeTreeJson(
@@ -1283,18 +1355,21 @@ export class AssistsXAsync {
             filePath?: string;
             prettyPrint?: boolean;
             timeout?: number;
+            scope?: NodeLookupScope;
         } = {}
     ): Promise<string> {
         const {
             filePath,
             prettyPrint = true,
             timeout,
+            scope,
         } = options;
 
         const response = await this.asyncCall(CallMethod.saveRootNodeTreeJson, {
             args: {
                 filePath,
                 prettyPrint,
+                ...(scope !== undefined ? { scope } : {}),
             },
             timeout,
         });

package/src/assistsx.ts

@@ -10,6 +10,7 @@ import { decodeBase64UTF8, generateUUID } from "./utils";
 import { AccessibilityEventFilter } from "./accessibility-event-filter";
 import { AppInfo } from "./app-info";
 import { DeviceInfo } from "./device-info";
+import type { NodeLookupScope } from "./node-lookup-scope";
 
 /**
  * 无障碍事件数据结构
@@ -76,7 +77,7 @@ export interface Screen {
 }
 
 /** 全局屏幕尺寸，在 assistsxCallback 初始化后自动加载 */
-export let screen: Screen | null = null;
+export let screen: Screen;
 
 // 初始化全局回调函数
 if (typeof window !== "undefined" && !window.assistsxCallback) {
@@ -246,14 +247,22 @@ export class AssistsX {
         filterViewId,
         filterDes,
         filterText,
+        scope,
     }: {
         filterClass?: string;
         filterViewId?: string;
         filterDes?: string;
         filterText?: string;
+        scope?: NodeLookupScope;
     } = {}): Node[] {
         const response = this.call(CallMethod.getAllNodes, {
-            args: { filterClass, filterViewId, filterDes, filterText },
+            args: {
+                filterClass,
+                filterViewId,
+                filterDes,
+                filterText,
+                ...(scope !== undefined ? { scope } : {}),
+            },
         });
         const data = response.getDataOrDefault([]);
         if (!Array.isArray(data)) {
@@ -434,8 +443,12 @@ export class AssistsX {
      * 获取当前应用包名
      * @returns 包名
      */
-    public static getPackageName(): string {
-        const response = this.call(CallMethod.getPackageName);
+    public static getPackageName(options: { scope?: NodeLookupScope } = {}): string {
+        const { scope } = options;
+        const response = this.call(
+            CallMethod.getPackageName,
+            scope !== undefined ? { args: { scope } } : {}
+        );
         return response.getDataOrDefault("");
     }
 
@@ -468,15 +481,23 @@ export class AssistsX {
             filterText,
             filterDes,
             node,
+            scope,
         }: {
             filterClass?: string;
             filterText?: string;
             filterDes?: string;
             node?: Node;
+            scope?: NodeLookupScope;
         } = {}
     ): Node[] {
         const response = this.call(CallMethod.findById, {
-            args: { id, filterClass, filterText, filterDes },
+            args: {
+                id,
+                filterClass,
+                filterText,
+                filterDes,
+                ...(scope !== undefined ? { scope } : {}),
+            },
             node,
         });
         const data = response.getDataOrDefault([]);
@@ -505,15 +526,23 @@ export class AssistsX {
             filterViewId,
             filterDes,
             node,
+            scope,
         }: {
             filterClass?: string;
             filterViewId?: string;
             filterDes?: string;
             node?: Node;
+            scope?: NodeLookupScope;
         } = {}
     ): Node[] {
         const response = this.call(CallMethod.findByText, {
-            args: { text, filterClass, filterViewId, filterDes },
+            args: {
+                text,
+                filterClass,
+                filterViewId,
+                filterDes,
+                ...(scope !== undefined ? { scope } : {}),
+            },
             node,
         });
         const data = response.getDataOrDefault([]);
@@ -542,15 +571,23 @@ export class AssistsX {
             filterViewId,
             filterDes,
             node,
+            scope,
         }: {
             filterText?: string;
             filterViewId?: string;
             filterDes?: string;
             node?: Node;
+            scope?: NodeLookupScope;
         } = {}
     ): Node[] {
         const response = this.call(CallMethod.findByTags, {
-            args: { className, filterText, filterViewId, filterDes },
+            args: {
+                className,
+                filterText,
+                filterViewId,
+                filterDes,
+                ...(scope !== undefined ? { scope } : {}),
+            },
             node,
         });
         const data = response.getDataOrDefault([]);
@@ -566,11 +603,17 @@ export class AssistsX {
     /**
      * 查找所有匹配文本的节点
      * @param text 要查找的文本
-     * @returns 节点数组
+     * @param options.scope 节点查找范围（可选）
      */
-    public static findByTextAllMatch(text: string): Node[] {
+    public static findByTextAllMatch(
+        text: string,
+        { scope }: { scope?: NodeLookupScope } = {}
+    ): Node[] {
         const response = this.call(CallMethod.findByTextAllMatch, {
-            args: { text },
+            args: {
+                text,
+                ...(scope !== undefined ? { scope } : {}),
+            },
         });
         const data = response.getDataOrDefault([]);
         if (!Array.isArray(data)) {
@@ -1130,7 +1173,7 @@ if (typeof window !== "undefined") {
     try {
         // 检查 assistsx 是否可用，如果可用则初始化屏幕尺寸
         if ((window as any).assistsx && typeof (window as any).assistsx.call === "function") {
-            screen = AssistsX.getScreenSize();
+            screen = AssistsX.getScreenSize() ?? { width: 0, height: 0 };
         }
     } catch (e) {
         // 如果初始化失败，screen 保持为 null

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./node-lookup-scope";
 export * from "./assistsx";
 export * from "./node";
 export * from "./call-method";

package/src/node-lookup-scope.ts

@@ -0,0 +1,10 @@
+/**
+ * 与 Android AssistsCore.NodeLookupScope / HTTP scope 查询参数一致的字符串取值。
+ */
+export type NodeLookupScope = "active_window" | "all_windows";
+
+/** 与 AssistsCore.NodeLookupScope.ActiveWindow 对应 */
+export const NODE_LOOKUP_SCOPE_ACTIVE_WINDOW: NodeLookupScope = "active_window";
+
+/** 与 AssistsCore.NodeLookupScope.AllWindows 对应 */
+export const NODE_LOOKUP_SCOPE_ALL_WINDOWS: NodeLookupScope = "all_windows";

package/src/step-async.ts

@@ -10,6 +10,7 @@ import { generateUUID } from "./utils";
 import { StepError } from "./step-error";
 import { AssistsXAsync } from "./assistsx-async";
 import { Step } from "./step";
+import type { NodeLookupScope } from "./node-lookup-scope";
 
 export class StepAsync {
     private step: Step;
@@ -73,11 +74,13 @@ export class StepAsync {
         filterViewId,
         filterDes,
         filterText,
+        scope,
     }: {
         filterClass?: string;
         filterViewId?: string;
         filterDes?: string;
         filterText?: string;
+        scope?: NodeLookupScope;
     } = {}): Promise<Node[]> {
         Step.assert(this.step.stepId);
         const nodes = await AssistsXAsync.getAllNodes({
@@ -85,6 +88,7 @@ export class StepAsync {
             filterViewId,
             filterDes,
             filterText,
+            scope,
         });
         Step.assert(this.step.stepId);
         Step.assignIdsToNodes(nodes, this.step.stepId);
@@ -105,11 +109,26 @@ export class StepAsync {
 
     /**
      * 获取当前应用包名
-     * @returns 包名
+     * @param timeout 超时时间(秒)，默认30秒
      */
-    public async getPackageName(): Promise<string> {
+    public async getPackageName(timeout?: number): Promise<string>;
+    /**
+     * 获取当前应用包名
+     * @param options.timeout 超时时间(秒)，默认30秒
+     * @param options.scope 节点查找范围（可选）
+     */
+    public async getPackageName(options: {
+        timeout?: number;
+        scope?: NodeLookupScope;
+    }): Promise<string>;
+    public async getPackageName(
+        timeoutOrOptions?: number | { timeout?: number; scope?: NodeLookupScope }
+    ): Promise<string> {
         Step.assert(this.step.stepId);
-        const result = await AssistsXAsync.getPackageName();
+        const result =
+            typeof timeoutOrOptions === "number"
+                ? await AssistsXAsync.getPackageName(timeoutOrOptions)
+                : await AssistsXAsync.getPackageName(timeoutOrOptions ?? {});
         Step.assert(this.step.stepId);
         return result;
     }
@@ -128,13 +147,20 @@ export class StepAsync {
             filterClass,
             filterText,
             filterDes,
-        }: { filterClass?: string; filterText?: string; filterDes?: string } = {}
+            scope,
+        }: {
+            filterClass?: string;
+            filterText?: string;
+            filterDes?: string;
+            scope?: NodeLookupScope;
+        } = {}
     ): Promise<Node[]> {
         Step.assert(this.step.stepId);
         const nodes = await AssistsXAsync.findById(id, {
             filterClass,
             filterText,
             filterDes,
+            scope,
         });
         Step.assert(this.step.stepId);
         Step.assignIdsToNodes(nodes, this.step.stepId);
@@ -155,13 +181,20 @@ export class StepAsync {
             filterClass,
             filterViewId,
             filterDes,
-        }: { filterClass?: string; filterViewId?: string; filterDes?: string } = {}
+            scope,
+        }: {
+            filterClass?: string;
+            filterViewId?: string;
+            filterDes?: string;
+            scope?: NodeLookupScope;
+        } = {}
     ): Promise<Node[]> {
         Step.assert(this.step.stepId);
         const nodes = await AssistsXAsync.findByText(text, {
             filterClass,
             filterViewId,
             filterDes,
+            scope,
         });
         Step.assert(this.step.stepId);
         Step.assignIdsToNodes(nodes, this.step.stepId);
@@ -182,13 +215,20 @@ export class StepAsync {
             filterText,
             filterViewId,
             filterDes,
-        }: { filterText?: string; filterViewId?: string; filterDes?: string } = {}
+            scope,
+        }: {
+            filterText?: string;
+            filterViewId?: string;
+            filterDes?: string;
+            scope?: NodeLookupScope;
+        } = {}
     ): Promise<Node[]> {
         Step.assert(this.step.stepId);
         const nodes = await AssistsXAsync.findByTags(className, {
             filterText,
             filterViewId,
             filterDes,
+            scope,
         });
         Step.assert(this.step.stepId);
         Step.assignIdsToNodes(nodes, this.step.stepId);
@@ -198,11 +238,33 @@ export class StepAsync {
     /**
      * 查找所有匹配文本的节点
      * @param text 要查找的文本
-     * @returns 节点数组
+     * @param timeout 超时时间(秒)，默认30秒
      */
-    public async findByTextAllMatch(text: string): Promise<Node[]> {
+    public async findByTextAllMatch(
+        text: string,
+        timeout?: number
+    ): Promise<Node[]>;
+    /**
+     * 查找所有匹配文本的节点
+     * @param text 要查找的文本
+     * @param options.timeout 超时时间(秒)，默认30秒
+     * @param options.scope 节点查找范围（可选）
+     */
+    public async findByTextAllMatch(
+        text: string,
+        options: { timeout?: number; scope?: NodeLookupScope }
+    ): Promise<Node[]>;
+    public async findByTextAllMatch(
+        text: string,
+        timeoutOrOptions?: number | { timeout?: number; scope?: NodeLookupScope }
+    ): Promise<Node[]> {
         Step.assert(this.step.stepId);
-        const nodes = await AssistsXAsync.findByTextAllMatch(text);
+        const nodes =
+            typeof timeoutOrOptions === "number"
+                ? await AssistsXAsync.findByTextAllMatch(text, timeoutOrOptions)
+                : timeoutOrOptions !== undefined
+                    ? await AssistsXAsync.findByTextAllMatch(text, timeoutOrOptions)
+                    : await AssistsXAsync.findByTextAllMatch(text);
         Step.assert(this.step.stepId);
         Step.assignIdsToNodes(nodes, this.step.stepId);
         return nodes;

package/src/step.ts

@@ -9,6 +9,7 @@ import { useStepStore } from "./step-state-store";
 import { generateUUID } from "./utils";
 import { StepError, StepStopError } from "./step-error";
 import { StepAsync } from "./step-async";
+import type { NodeLookupScope } from "./node-lookup-scope";
 
 // 步骤结果类型，可以是Step实例或undefined
 export type StepResult = Step | undefined;
@@ -631,11 +632,13 @@ export class Step {
         filterViewId,
         filterDes,
         filterText,
+        scope,
     }: {
         filterClass?: string;
         filterViewId?: string;
         filterDes?: string;
         filterText?: string;
+        scope?: NodeLookupScope;
     } = {}): Node[] {
         Step.assert(this.stepId);
         const nodes = AssistsX.getAllNodes({
@@ -643,6 +646,7 @@ export class Step {
             filterViewId,
             filterDes,
             filterText,
+            scope,
         });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
@@ -663,11 +667,11 @@ export class Step {
 
     /**
      * 获取当前应用包名
-     * @returns 包名
+     * @param options.scope 节点查找范围（可选）
      */
-    public getPackageName(): string {
+    public getPackageName(options: { scope?: NodeLookupScope } = {}): string {
         Step.assert(this.stepId);
-        const result = AssistsX.getPackageName();
+        const result = AssistsX.getPackageName(options);
         Step.assert(this.stepId);
         return result;
     }
@@ -686,10 +690,21 @@ export class Step {
             filterClass,
             filterText,
             filterDes,
-        }: { filterClass?: string; filterText?: string; filterDes?: string } = {}
+            scope,
+        }: {
+            filterClass?: string;
+            filterText?: string;
+            filterDes?: string;
+            scope?: NodeLookupScope;
+        } = {}
     ): Node[] {
         Step.assert(this.stepId);
-        const nodes = AssistsX.findById(id, { filterClass, filterText, filterDes });
+        const nodes = AssistsX.findById(id, {
+            filterClass,
+            filterText,
+            filterDes,
+            scope,
+        });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
         return nodes;
@@ -709,13 +724,20 @@ export class Step {
             filterClass,
             filterViewId,
             filterDes,
-        }: { filterClass?: string; filterViewId?: string; filterDes?: string } = {}
+            scope,
+        }: {
+            filterClass?: string;
+            filterViewId?: string;
+            filterDes?: string;
+            scope?: NodeLookupScope;
+        } = {}
     ): Node[] {
         Step.assert(this.stepId);
         const nodes = AssistsX.findByText(text, {
             filterClass,
             filterViewId,
             filterDes,
+            scope,
         });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
@@ -736,13 +758,20 @@ export class Step {
             filterText,
             filterViewId,
             filterDes,
-        }: { filterText?: string; filterViewId?: string; filterDes?: string } = {}
+            scope,
+        }: {
+            filterText?: string;
+            filterViewId?: string;
+            filterDes?: string;
+            scope?: NodeLookupScope;
+        } = {}
     ): Node[] {
         Step.assert(this.stepId);
         const nodes = AssistsX.findByTags(className, {
             filterText,
             filterViewId,
             filterDes,
+            scope,
         });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
@@ -752,11 +781,14 @@ export class Step {
     /**
      * 查找所有匹配文本的节点
      * @param text 要查找的文本
-     * @returns 节点数组
+     * @param options.scope 节点查找范围（可选）
      */
-    public findByTextAllMatch(text: string): Node[] {
+    public findByTextAllMatch(
+        text: string,
+        { scope }: { scope?: NodeLookupScope } = {}
+    ): Node[] {
         Step.assert(this.stepId);
-        const nodes = AssistsX.findByTextAllMatch(text);
+        const nodes = AssistsX.findByTextAllMatch(text, { scope });
         Step.assert(this.stepId);
         Step.assignIdsToNodes(nodes, this.stepId);
         return nodes;