본문으로 건너뛰기
모든 도구

ui_find_element

화면, 윈도우 및 인터페이스 · macOS · Windows

효과: 읽기. 상태: 조건부 제공.

‘조건부 제공’은 도구가 버전, 플랫폼, 권한, 계정 또는 설정에 따라 달라질 수 있음을 뜻하며 모든 설치에서 활성화되었다는 의미는 아닙니다.

macOS

목적

GUI 자동화로 네이티브 앱 인터페이스를 제어합니다. 앱의 손쉬운 사용 트리에서 역할 및/또는 레이블로 요소(버튼, 필드, 메뉴 등)를 찾습니다. app_bundle_id 또는 window_id로 범위를 제한합니다. 이 세션에서 ui_click / ui_get_element에 사용할 수 있는 불투명 element_ref와 역할, 레이블, 경계, 포커스 상태를 반환하며 앱이 AXEnabled를 게시할 때만 `enabled`를 포함합니다. 그렇지 않으면 `enabled_unknown: true`이며 비활성이라는 뜻이 아닙니다. 앱에 접근할 수 있지만 일치 항목이 없으면 found=false이고, 앱이 없으면 app_not_found 명시적 오류입니다. 손쉬운 사용 권한이 필요합니다.

필수 입력

이 플랫폼의 스키마에는 필수 입력이 선언되어 있지 않습니다. 선택 항목이나 실행 요구 사항은 여전히 있을 수 있습니다.

권한 및 확인

스키마에 명시적 확인 매개변수가 없습니다. 이는 무단 작업을 허용하지 않습니다. 효과를 검토하고 승인을 받으세요.

영문 정식 기술 스키마 — 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 트리에서 역할 및/또는 레이블로 요소(버튼, 필드, 메뉴 등)를 찾습니다. `app`에 프로세스 이름(예: "notepad") 또는 창 제목 일부를 지정해 범위를 제한합니다. 이 세션에서 ui_click / ui_type / ui_get_element에 사용할 수 있는 불투명 element_ref와 역할, 레이블, 경계, 활성화 및 포커스 상태를 반환합니다. `role`은 UIA 컨트롤 유형(Button, Edit, CheckBox, MenuItem, Hyperlink, Text 등)입니다. 정확한 이름은 ui_read_tree로 확인하세요. 앱에 접근할 수 있지만 일치 항목이 없으면 found=false이고, 앱이 없으면 app_not_found 명시적 오류입니다.

필수 입력

이 플랫폼의 스키마에는 필수 입력이 선언되어 있지 않습니다. 선택 항목이나 실행 요구 사항은 여전히 있을 수 있습니다.

권한 및 확인

스키마에 명시적 확인 매개변수가 없습니다. 이는 무단 작업을 허용하지 않습니다. 효과를 검토하고 승인을 받으세요.

영문 정식 기술 스키마 — 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"
}

문서 예시

ui_find_element 문서 예시입니다. 이 예시를 실행하지 마세요. 표시된 인수는 가상 데이터 세트에 속합니다. 실제 호출 전에 실제 식별자를 확인하고 승인을 받으세요.

{
  "label": "Save"
}