element_tap

Instructions

Implementation Reference

• src/tools/element.ts:113-192 (handler)

  The `createTapElementTool` function returns the tool definition including the `execute` handler that resolves an element by selector (with optional innerSelector and [index=N] syntax), calls `.tap()` on it, optionally waits, and returns a result text. This is the main handler logic for the 'element_tap' tool.

  function createTapElementTool(manager: WeappAutomatorManager): AnyTool {
    return {
      name: "element_tap",
      description: "通过 CSS 选择器模拟点击 WXML 元素。支持 [index=N] 语法选择第 N 个元素。如需点击自定义组件内部的元素，请使用 innerSelector 参数：selector 设为组件 ID 选择器(如 #my-component)或标签选择器，innerSelector 设为组件内部元素的选择器。",
      parameters: tapElementParameters,
      execute: async (rawArgs, context: ToolContext) =>
        withUserErrorResult(async () => {
        const args = tapElementParameters.parse(rawArgs ?? {});
        const waitMs = args.waitMs;
  
        return manager.withPage(
          context.log,
          { overrides: args.connection },
          async (page) => {
            let selector = args.selector;
            let indexHint: number | undefined;
  
            const parsed = parseSelectorWithIndex(selector);
            if (parsed) {
              selector = parsed.baseSelector;
              indexHint = parsed.index;
            }
  
            let element;
            if (indexHint === undefined) {
              element = await resolveElement(
                page,
                args.selector,
                args.innerSelector
              );
            } else {
              if (typeof page.$$ !== "function") {
                throw new UserError("当前页面不支持查询元素数组。");
              }
  
              let elements = await page.$$(selector);
              if (!Array.isArray(elements) || elements.length === 0) {
                throw new UserError(`未找到元素: "${selector}"`);
              }
  
              if (indexHint < 0 || indexHint >= elements.length) {
                throw new UserError(`索引 ${indexHint} 超出范围 (0-${elements.length - 1})。`);
              }
  
              element = elements[indexHint];
  
              if (args.innerSelector) {
                if (typeof element.$ !== "function") {
                  throw new UserError(`元素 "${args.selector}" 不支持查询内部元素。`);
                }
                const inner = await element.$(args.innerSelector);
                if (!inner) {
                  throw new UserError(
                    `在元素 "${args.selector}" 内未找到选择器 "${args.innerSelector}" 对应的元素。`
                  );
                }
                element = inner;
              }
            }
  
            try {
              await element.tap();
            } catch (error) {
              const message = error instanceof Error ? error.message : String(error);
              throw new UserError(
                `点击元素 "${args.selector}"${args.innerSelector ? ` -> "${args.innerSelector}"` : ""} 失败: ${message}`
              );
            }
  
            if (waitMs) {
              await waitOnPage(page, waitMs);
            }
  
            return toTextResult(
              `已点击元素 "${args.selector}"${args.innerSelector ? ` -> "${args.innerSelector}"` : ""}${waitMs ? ` 并等待 ${waitMs}ms` : ""}。`
            );
          }
        );
        }),
    };

• src/tools/element.ts:19-23 (schema)

  The `tapElementParameters` Zod schema defines the input parameters for the element_tap tool: selector (required), innerSelector (optional), waitMs (optional), and connection (optional via spread of connectionContainerSchema).

  const tapElementParameters = connectionContainerSchema.extend({
    selector: z.string().trim().min(1),
    innerSelector: z.string().trim().min(1).optional(),
    waitMs: z.coerce.number().int().nonnegative().optional(),
  });

• src/tools.ts:7-13 (registration)

  The `createTools` function in src/tools.ts aggregates all tools, including `createElementTools(manager)` which creates the 'element_tap' tool.

  export function createTools(manager: WeappAutomatorManager): AnyTool[] {
    return [
      ...createApplicationTools(manager),
      ...createPageTools(manager),
      ...createElementTools(manager),
    ];
  }

• src/tools/element.ts:94-111 (registration)

  The `createElementTools` function returns an array of tool creators including `createTapElementTool(manager)`, which registers 'element_tap' in the tool list.

  export function createElementTools(
    manager: WeappAutomatorManager
  ): AnyTool[] {
    return [
      createTapElementTool(manager),
      createInputTextTool(manager),
      createCallElementMethodTool(manager),
      createGetElementDataTool(manager),
      createSetElementDataTool(manager),
      createGetInnerElementTool(manager),
      createGetInnerElementsTool(manager),
      createGetElementWxmlTool(manager),
      createGetElementStylesTool(manager),
      createScrollToTool(manager),
      createGetAttributesTool(manager),
      createGetBoundingClientRectTool(manager),
    ];
  }

• src/tools/common.ts:286-296 (helper)

  The `parseSelectorWithIndex` helper parses the [index=N] syntax from the selector string, used by the element_tap handler to support index-based element selection.

  export function parseSelectorWithIndex(selector: string): { baseSelector: string; index: number } | null {
    // 匹配 selector[index=N] 语法
    const match = selector.match(/^(.+?)\[index=(\d+)\]$/);
    if (match) {
      return {
        baseSelector: match[1],
        index: parseInt(match[2], 10),
      };
    }
    return null;
  }