ui_find_element

Экран, окна и интерфейс · macOS · Windows

Эффект: чтение. Статус: условно доступен.

«Условная доступность» означает, что инструмент может зависеть от версии, платформы, разрешений, учётной записи или настроек. Он доступен не во всех установках.

macOS

Назначение

Автоматизация GUI — управление интерфейсом нативного приложения. Находит элемент (кнопку, поле, меню…) в дереве доступности приложения по роли и/или подписи. Ограничьте поиск с помощью app_bundle_id или window_id. Возвращает непрозрачный element_ref (который можно использовать в ui_click / ui_get_element в этой сессии), а также role, label, bounds, focused и `enabled` только когда приложение публикует AXEnabled (иначе `enabled_unknown: true`, что НЕ означает отключенное состояние). found=false, когда приложение доступно, но совпадающий элемент отсутствует; app_not_found — явная ошибка. Требуется разрешение Accessibility.

Обязательные входные данные

Схема этой платформы не объявляет обязательных входных данных. Необязательные селекторы или требования среды всё же могут применяться.

Разрешения и подтверждение

Схема не объявляет явного параметра подтверждения. Это не разрешает действовать без согласия: проверьте эффект и получите разрешение.

Используйте на этой платформе только приложения, учетные записи и ресурсы, разрешенные пользователем. Требования к подключению и разрешениям приведены в описании инструмента для конкретной платформы; этот каталог не заявляет о дополнительных областях OAuth или разрешениях OS.

Каноническая техническая схема на английском — 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. Находит элемент (кнопку, поле, меню…) в дереве 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 — явная ошибка.

Обязательные входные данные

Разрешения и подтверждение

Используйте на этой платформе только приложения, учетные записи и ресурсы, разрешенные пользователем. Требования к подключению и разрешениям приведены в описании инструмента для конкретной платформы; этот каталог не заявляет о дополнительных областях OAuth или разрешениях OS.

Каноническая техническая схема на английском — Windows

{
  "properties": {
    "app": {
      "description": "Scope to this app: process name (e.g. notepad) or a window-title substring.",
      "type": "string"
    },
    "index": {
      "description": "Which match to return if several (default 0).",
      "type": "integer"
    },
    "label": {
      "description": "Name/HelpText/Value to match.",
      "type": "string"
    },
    "match": {
      "description": "Default contains.",
      "enum": [
        "exact",
        "contains"
      ],
      "type": "string"
    },
    "role": {
      "description": "UIA control type, e.g. Button, Edit, MenuItem, CheckBox.",
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

Пример для документации

{
  "label": "Save"
}