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).",
      "type": "integer"
    },
    "label": {
      "description": "AX title/description to match.",
      "type": "string"
    },
    "match": {
      "description": "Default contains.",
      "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"
}