選擇器字段說明

該模組在 20260507 以後版本方可使用

選擇器是一個 Lua 表，用於描述要查找或操作的 UI 元素。建議優先使用可讀文字和角色組合定位，必要時再加 index 區分同名元素。

範例

local selector = {
    title = "搜索",
    role = "text_field",
}

local item = ui_element.find(selector)

字段

• title / text
  文字型，匹配元素的可讀標題。兩者含義相同。
• text_contains
  文字型，匹配可讀標題中包含的子串。
• value
  文字型、數值型或布林型，匹配元素目前值。
• value_contains
  文字型，匹配元素值中包含的子串。
• identifier
  文字型，匹配元素標識符。並非所有 App 都會提供。
• bundle_id
  文字型，匹配元素所屬 App 的 bundle identifier。
• role
  文字型，匹配元素類型。常用值包括 button、text_field、static_text、switch、checkbox、radio、slider、picker、scrollable、link、image、keyboard_key。
• traits
  文字型或文字陣列，匹配元素特徵名稱，例如 Button、StaticText、Toggle、Adjustable。
• visible
  布林型，匹配元素是否可見。
• hittable
  布林型，匹配元素目前是否可被命中。動作類介面通常需要目標可命中。
• checked
  布林型，匹配開關、勾選框、單選項等可確認狀態。
• selected
  布林型，匹配元素是否處於選中狀態。
• index
  整數型，當有多個匹配項時取第幾個，按 Lua 習慣從 1 開始。

說明

不建議把座標、尺寸、視窗標識等容易變化的字段作為主要選擇器。 多個元素同時匹配且沒有指定 index 時，動作類介面可能返回 nil, "ambiguous target"。 不同 App、不同 iOS 版本暴露的字段可能不同，應為關鍵字段缺失預留處理邏輯。