元素字段說明

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

查詢介面返回的元素是普通 Lua 表。字段來自目前介面暴露的資訊，不同 App 與控制項類型可能返回不同字段。

常見字段

• text
  文字型，元素的可讀標題。
• value
  任意類型，元素目前值。文字框通常是目前文字，開關可能是 0 或 1，滑塊可能是百分比文字。
• identifier
  文字型，元素標識符。
• hint
  文字型，系統輔助提示。
• bundleId
  文字型，元素所屬 App 的 bundle identifier。
• x / y / width / height
  整數型，元素區域，單位為物理像素。
• centerPoint
  表型，元素中心點，單位為物理像素，例如 { x = 100, y = 200 }。
• children
  表型，子元素陣列。展開深度由 max_level 控制。
• traits
  整數型，元素特徵值。
• traitsDescription
  表型，元素特徵名稱陣列，例如 Button、StaticText、Toggle、Adjustable。
• isVisible
  布林型，元素是否可見。
• isSelected
  布林型，元素是否被選中。
• isToggle
  布林型，元素是否像開關控制項。
• isAdjustable
  布林型，元素是否支援增減調節。
• checked
  布林型，開關、勾選框、單選項等控制項的確認狀態。讀不到可靠狀態時可能不存在。
• hasTextEntry
  布林型，元素是否像文字輸入目標。
• isKeyboardKey
  布林型，元素是否像鍵盤按鍵。
• absoluteValue
  實數型，滑塊等可調節控制項可能返回的歸一化值。

命中狀態字段

這些字段僅在啟用 include_hit_state、hit_test、fallback_hit_test 或執行動作復核時可能出現：

• canHit
  布林型，目前是否能從頂層命中。
• hitVerified
  布林型，是否已經驗證過命中狀態。
• hitTestPoint
  表型，命中點，單位為物理像素。

說明

元素字段適合讀取與判斷目前介面狀態。 如果需要穩定定位，優先使用 text、role、checked、selected 等語義字段組成選擇器。 介面變化後應重新查詢元素或重新取得快照。