元素字段说明

该模块在 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 等语义字段组成选择器。 界面变化后应重新查询元素或重新获取快照。