ui_find_element

画面、ウインドウ、UI · macOS · Windows

効果: 読み取り. 状態: 条件付き提供.

「条件付き提供」は、バージョン、プラットフォーム、権限、アカウント、設定に依存する可能性を示し、すべての環境で有効という意味ではありません。

macOS

目的

GUI 自動化でネイティブアプリの画面を操作します。アクセシビリティツリーから role や label で要素（ボタン、フィールド、メニューなど）を検索します。app_bundle_id または window_id で限定できます。このセッションで ui_click / ui_get_element に渡せる不透明な element_ref と、role、label、bounds、focused を返します。`enabled` はアプリが AXEnabled を公開する場合だけ返り、それ以外の `enabled_unknown: true` は無効を意味しません。アプリに到達できても一致しなければ found=false、アプリ不在は明示的な app_not_found エラーです。アクセシビリティ権限が必要です。

必須入力

このプラットフォームのスキーマには必須入力が宣言されていません。任意の選択項目や実行要件が存在する場合があります。

権限と確認

スキーマには明示的な確認パラメータがありません。これは無許可の操作を認めるものではありません。効果を確認し、承認を得てください。

このプラットフォームでは、ユーザーが許可したアプリ、アカウント、リソースだけを使用してください。接続と権限の要件については、このツールのプラットフォーム固有の説明を参照してください。このカタログは、追加の 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), 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"
}

ドキュメント例

ui_find_element のドキュメント例です。この例は実行しないでください。表示される引数は架空のデータセットに属します。実際に呼び出す前に実在する識別子を確認し、承認を得てください。

{
  "label": "Save"
}

Windows

目的

GUI 自動化で Windows ネイティブアプリの画面を操作します。UI Automation ツリーから role や label で要素を検索します。`app`（notepad などのプロセス名またはウィンドウタイトルの一部）で限定できます。このセッションで ui_click / ui_type / ui_get_element に渡せる不透明な element_ref と 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"
}