元素字段說明
該模組在 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等語義字段組成選擇器。 介面變化後應重新查詢元素或重新取得快照。