通用選項說明

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

多個 ui_element 介面接受選項表，用於指定目標 App、返回數量、遞歸深度、命中驗證和滾動步進。

查詢選項

local options = {
    pid = app.front_pid(),
    max_level = 2,
    max_elements = 200,
    include_hit_state = true,
}

• pid 整數型，指定目標 App 的行程標識符。不傳時通常使用前台 App。
• max_level 整數型，子元素遞歸深度。常用 1 或 2 控制返回資料量。
• max_elements 整數型，最多返回的頂層元素數量。
• fallback_children 布林型，普通清單為空時嘗試讀取子元素。預設值隨介面不同而不同。
• include_hit_state 布林型，是否補充命中狀態字段。
• hit_test 布林型，是否啟用螢幕採樣命中。普通腳本通常不需要開啟。
• fallback_hit_test 布林型，普通清單為空時是否嘗試螢幕採樣命中。
• hit_test_spacing 數值型，螢幕採樣間距，單位為邏輯座標。預設 40。

動作選項

• point 表型，指定滾動或命中使用的座標點，例如 { x = 200, y = 700 }，單位為物理像素。
• x / y 整數型，和 point 等價，可直接放在選項表中。
• steps 數值型，用於滾動、增加或減少操作的步進參數。具體效果取決於目標控制項。

說明

list_text_elements() 為兼容舊腳本，預設更保守。 find()、find_all()、snapshot() 和動作類介面更適合新腳本直接使用。 hit_test 可能返回更接近目前頂層介面的元素，但成本更高，建議只在普通查詢拿不到元素時使用。