通用选项说明

该模块在 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 可能返回更接近当前顶层界面的元素，但成本更高，建议只在普通查询拿不到元素时使用。