Ir para o conteúdo
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 não 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), 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"
}

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"
}