Todas las herramientas

ui_find_element

Pantalla, ventanas e interfaz · macOS · Windows

Efecto: lectura. Estado: disponibilidad controlada.

«Disponibilidad controlada» significa que la herramienta figura en los artefactos publicados y puede depender de versión, plataforma, permisos, cuenta o configuración. Esta referencia no promete que esté activa en todas las instalaciones. Que una herramienta figure para macOS no implica que esté disponible en Windows, ni al revés.

macOS

Propósito

Automatización GUI: controle la interfaz de una aplicación nativa. Busca un elemento (botón, campo, menú...) en el árbol de accesibilidad de una aplicación por función y/o etiqueta (`label`). Alcance con app_bundle_id o window_id. Devuelve un element_ref opaco (utilizable por ui_click / ui_get_element en esta sesión) más rol, etiqueta, límites, enfocado y `enabled` solo cuando la aplicación publica AXEnabled (de lo contrario, `enabled_unknown: true`, que significa NO deshabilitado). found=false cuando se puede acceder a la aplicación pero ningún elemento coincide; app_not_found es un error explícito. Requiere permiso de accesibilidad.

Entradas obligatorias

El esquema de esta plataforma no declara entradas obligatorias. Aun así, pueden existir selectores opcionales o requisitos de ejecución.

Permisos y confirmación

El esquema no declara un parámetro explícito de confirmación. Esto no autoriza a actuar sin permiso: revisa el efecto y obtén autorización antes de una llamada real.

Esquema técnico canónico en 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"
}

Ejemplo documental

Ejemplo de documentación para ui_find_element. No ejecutes este ejemplo. Los argumentos mostrados pertenecen a un conjunto de datos ficticio; resuelve identificadores reales y obtén autorización antes de una llamada real.

{
  "label": "Save"
}

Windows

Propósito

Automatización GUI: controle la interfaz de una aplicación nativa de Windows. Busca un elemento (botón, campo, menú...) en el árbol de automatización de la interfaz de usuario de una aplicación por función y/o etiqueta (`label`). Alcance con `app` (nombre de proceso como "bloc de notas" o una subcadena de título de ventana). Devuelve un element_ref opaco (utilizable por ui_click / ui_type / ui_get_element en esta sesión) más rol, etiqueta, límites, habilitado, enfocado. `role` es un tipo de control UIA (Botón, Editar, Casilla de verificación, Elemento de menú, Hipervínculo, Texto…): ejecute ui_read_tree para ver los nombres exactos. found=false cuando se puede acceder a la aplicación pero no hay nada que coincida; app_not_found es un error explícito.

Entradas obligatorias

El esquema de esta plataforma no declara entradas obligatorias. Aun así, pueden existir selectores opcionales o requisitos de ejecución.

Permisos y confirmación

El esquema no declara un parámetro explícito de confirmación. Esto no autoriza a actuar sin permiso: revisa el efecto y obtén autorización antes de una llamada real.

Esquema técnico canónico en 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"
}

Ejemplo documental

Ejemplo de documentación para ui_find_element. No ejecutes este ejemplo. Los argumentos mostrados pertenecen a un conjunto de datos ficticio; resuelve identificadores reales y obtén autorización antes de una llamada real.

{
  "label": "Save"
}