ui_find_element

屏幕、窗口与界面 · macOS · Windows

效果: 读取. 状态: 受限可用.

“受限可用”表示工具可能取决于版本、平台、权限、账户或配置，并不表示它在所有安装中都已启用。

macOS

用途

GUI 自动化：控制原生应用的界面。根据 role 和/或 label，在应用的辅助功能树中查找元素（按钮、字段、菜单等）。可用 app_bundle_id 或 window_id 限定范围。返回不透明的 element_ref（当前会话中可供 ui_click / ui_get_element 使用），以及 role、label、bounds、focused；仅当应用发布 AXEnabled 时才返回 `enabled`，否则返回 `enabled_unknown: true`，这并不表示已禁用。应用可访问但无元素匹配时返回 found=false；app_not_found 是明确错误。需要辅助功能权限。

必填输入

此平台的架构未声明必填输入，但仍可能存在可选选择器或运行时要求。

权限与确认

架构未声明明确的确认参数。这并不代表可以未经许可操作；请检查效果并取得授权。

仅使用用户在此平台上授权的应用、账户和资源。请查阅此工具针对平台的说明，以了解其连接和权限要求；本目录不声称需要额外的 OAuth 范围或操作系统授权。

英文规范技术架构 — macOS

{
  "properties": {
    "app_bundle_id": {
      "description": "Scope the search to this app.",
      "type": "string"
    },
    "index": {
      "description": "Which match to return if several (default 0), counted after the exact-first ordering.",
      "type": "integer"
    },
    "label": {
      "description": "AX title/description to match.",
      "type": "string"
    },
    "match": {
      "description": "Default contains. With contains, a label that equals the query (ignoring case and spacing) is preferred over longer labels that merely contain it (label \"Reply\" returns \"Reply\", not \"Reply All\"). When several elements match equally well the response has ambiguous: true and the candidates; the first is still returned.",
      "enum": [
        "exact",
        "contains"
      ],
      "type": "string"
    },
    "role": {
      "description": "AX role, e.g. AXButton, AXMenuItem, AXTextField.",
      "type": "string"
    },
    "window_id": {
      "description": "Alternatively scope by a window_id from list_windows.",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

文档示例

ui_find_element 的文档示例。请勿执行此示例。所示参数属于虚构数据集；在实际调用前，请解析真实标识符并获得授权。

{
  "label": "Save"
}

Windows

用途

GUI 自动化：控制原生 Windows 应用的界面。根据 role 和/或 label，在应用的 UI Automation 树中查找元素（按钮、字段、菜单等）。可用 `app` 限定范围，它可以是进程名称（例如“notepad”）或窗口标题的子字符串。返回不透明的 element_ref（当前会话中可供 ui_click / ui_type / ui_get_element 使用），以及 role、label、bounds、enabled、focused。`role` 是 UIA 控件类型（Button、Edit、CheckBox、MenuItem、Hyperlink、Text 等）；运行 ui_read_tree 可查看准确名称。应用可访问但无匹配项时返回 found=false；app_not_found 是明确错误。