Todas as ferramentas

ui_find_element

Ecrã, janelas e interface · macOS · Windows

Efeito: leitura. Estado: disponibilidade condicionada.

«Disponibilidade condicionada» significa que a ferramenta pode depender da versão, plataforma, permissões, conta ou configuração. Não significa que esteja ativa em todas as instalações.

macOS

Finalidade

Automação GUI — controle a interface de um aplicativo nativo. Encontra um elemento (botão, campo, menu…) na árvore de acessibilidade de um aplicativo por função e/ou rótulo. Escopo com app_bundle_id ou window_id. Retorna um element_ref opaco (utilizável por ui_click/ui_get_element nesta sessão) mais função, rótulo, limites, foco e `enabled` somente quando o aplicativo publica AXEnabled (caso contrário `enabled_unknown: true`, que NOT significa desabilitado). found=false quando o aplicativo está acessível, mas nenhum elemento corresponde; app_not_found é um erro explícito. Requer permissão de acessibilidade.

Entradas obrigatórias

O esquema desta plataforma não declara entradas obrigatórias. Ainda podem existir seletores opcionais ou requisitos de execução.

Permissões e confirmação

O esquema não declara um parâmetro explícito de confirmação. Isto não autoriza qualquer ação sem permissão; reveja o efeito e obtenha autorização.

Esquema técnico canónico em inglês — 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"
}

Exemplo documental

Exemplo de documentação para ui_find_element. Não execute este exemplo. Os argumentos apresentados pertencem a um conjunto de dados fictício; resolva identificadores reais e obtenha autorização antes de uma chamada real.

{
  "label": "Save"
}

Windows

Finalidade

Automação GUI — controle uma interface nativa do Windows app. Encontra um elemento (botão, campo, menu…) na árvore UI Automation de um app por role e/ou rótulo. Escopo com `app` (nome do processo como "bloco de notas" ou uma substring do título da janela). Retorna um element_ref opaco (utilizável por ui_click/ui_type/ui_get_element nesta sessão) mais role, rótulo, limites, ativado, focado. `role` é um tipo de controle UIA (Button, Edit, CheckBox, MenuItem, Hyperlink, Text…) - execute ui_read_tree para ver os nomes exatos. found=false quando app está acessível, mas nada corresponde; app_not_found é um erro explícito.

Entradas obrigatórias

O esquema desta plataforma não declara entradas obrigatórias. Ainda podem existir seletores opcionais ou requisitos de execução.

Permissões e confirmação

O esquema não declara um parâmetro explícito de confirmação. Isto não autoriza qualquer ação sem permissão; reveja o efeito e obtenha autorização.

Esquema técnico canónico em inglês — 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"
}

Exemplo documental

Exemplo de documentação para ui_find_element. Não execute este exemplo. Os argumentos apresentados pertencem a um conjunto de dados fictício; resolva identificadores reais e obtenha autorização antes de uma chamada real.

{
  "label": "Save"
}