Vai al contenuto
Tutti gli strumenti

ui_find_element

Schermo, finestre e interfaccia · macOS · Windows

Effetto: lettura. Stato: disponibilità condizionata.

«Disponibilità condizionata» indica che lo strumento può dipendere da versione, piattaforma, autorizzazioni, account o configurazione. Non è necessariamente attivo ovunque.

macOS

Scopo

Automazione GUI: controlla l’interfaccia di un’app nativa. Trova un elemento (pulsante, campo, menu…) nell’albero di accessibilità di un’app in base al ruolo e/o all’etichetta. Limita l’ambito con app_bundle_id o window_id. Restituisce un element_ref opaco (utilizzabile da ui_click / ui_get_element in questa sessione) insieme a ruolo, etichetta, limiti, stato attivo e `enabled` solo quando l’app pubblica AXEnabled (altrimenti `enabled_unknown: true`, che NON significa disabilitato). found=false quando l’app è raggiungibile ma nessun elemento corrisponde; app_not_found è un errore esplicito. Richiede l’autorizzazione Accessibilità.

Input obbligatori

Lo schema di questa piattaforma non dichiara input obbligatori. Possono comunque esistere selettori facoltativi o requisiti di esecuzione.

Autorizzazioni e conferma

Lo schema non dichiara un parametro di conferma esplicito. Ciò non autorizza azioni senza permesso: controlla l’effetto e ottieni l’autorizzazione.

Schema tecnico canonico in inglese — 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"
}

Esempio documentale

Esempio di documentazione per ui_find_element. Non eseguire questo esempio. Gli argomenti mostrati appartengono a un set di dati fittizio; individua gli identificatori reali e ottieni l’autorizzazione prima di una chiamata reale.

{
  "label": "Save"
}

Windows

Scopo

Automazione GUI: controlla l’interfaccia di un’app nativa Windows. Trova un elemento (pulsante, campo, menu…) nell’albero UI Automation di un’app in base al ruolo e/o all’etichetta. Limita l’ambito con `app` (il nome del processo, come "notepad", oppure una sottostringa del titolo della finestra). Restituisce un element_ref opaco (utilizzabile da ui_click / ui_type / ui_get_element in questa sessione) insieme a ruolo, etichetta, limiti, stato abilitato e stato attivo. `role` è un tipo di controllo UIA (Button, Edit, CheckBox, MenuItem, Hyperlink, Text…): esegui ui_read_tree per vedere i nomi esatti. found=false quando l’app è raggiungibile ma nulla corrisponde; app_not_found è un errore esplicito.

Input obbligatori

Lo schema di questa piattaforma non dichiara input obbligatori. Possono comunque esistere selettori facoltativi o requisiti di esecuzione.

Autorizzazioni e conferma

Lo schema non dichiara un parametro di conferma esplicito. Ciò non autorizza azioni senza permesso: controlla l’effetto e ottieni l’autorizzazione.

Schema tecnico canonico in inglese — 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"
}

Esempio documentale

Esempio di documentazione per ui_find_element. Non eseguire questo esempio. Gli argomenti mostrati appartengono a un set di dati fittizio; individua gli identificatori reali e ottieni l’autorizzazione prima di una chiamata reale.

{
  "label": "Save"
}