选择器字段说明

该模块在 20260507 以后版本方可使用

选择器是一个 Lua 表，用于描述要查找或操作的 UI 元素。建议优先使用可读文本和角色组合定位，必要时再加 index 区分同名元素。

示例

local selector = {
    title = "搜索",
    role = "text_field",
}

local item = ui_element.find(selector)

字段

• title / text
  文本型，匹配元素的可读标题。两者含义相同。
• text_contains
  文本型，匹配可读标题中包含的子串。
• value
  文本型、数值型或布尔型，匹配元素当前值。
• value_contains
  文本型，匹配元素值中包含的子串。
• identifier
  文本型，匹配元素标识符。并非所有 App 都会提供。
• bundle_id
  文本型，匹配元素所属 App 的 bundle identifier。
• role
  文本型，匹配元素类型。常用值包括 button、text_field、static_text、switch、checkbox、radio、slider、picker、scrollable、link、image、keyboard_key。
• traits
  文本型或文本数组，匹配元素特征名称，例如 Button、StaticText、Toggle、Adjustable。
• visible
  布尔型，匹配元素是否可见。
• hittable
  布尔型，匹配元素当前是否可被命中。动作类接口通常需要目标可命中。
• checked
  布尔型，匹配开关、勾选框、单选项等可确认状态。
• selected
  布尔型，匹配元素是否处于选中状态。
• index
  整数型，当有多个匹配项时取第几个，按 Lua 习惯从 1 开始。

说明

不建议把坐标、尺寸、窗口标识等容易变化的字段作为主要选择器。 多个元素同时匹配且没有指定 index 时，动作类接口可能返回 nil, "ambiguous target"。 不同 App、不同 iOS 版本暴露的字段可能不同，应为关键字段缺失预留处理逻辑。