WebView Query 查询器

WebView 内 DOM 元素的查询器

概述

WebView Query 与 App Query 共享相同的 API，用于在 WebView 内查找 DOM 元素。

约束组合逻辑

所有约束条件之间是 AND（且） 关系，元素必须同时满足所有约束才会被匹配。

技术说明

WebView 将 DOM 结构暴露给 AccessibilityService，Query 通过 AccessibilityNodeInfo 访问这些元素。

创建查询器

node.webview()

创建 WebView 内的查询器。

-- 在第一个 WebView 内查询
local query = node.webview()

-- 在第 n 个 WebView 内查询（按 DFS 顺序）
local query = node.webview(2)  -- 第 2 个 WebView

参数：

参数	类型	必填	说明
n	number	否	第几个 WebView，默认 1

返回值： Query - 查询器对象

说明：

如果找不到 WebView，后续 get() 返回 nil，all() 返回空表
WebView 按深度优先顺序编号

边界条件：

n = 0 - 无效，等效于 n = 1
n 超过 WebView 数量 - 后续查询返回空
负数 n - 无效，返回空查询

约束方法

WebView Query 支持与 App Query 相同的约束方法：

字符串约束

方法	说明
`.id(id)`	元素 ID
`.idContains(text)`	ID 包含
`.idStartsWith(text)`	ID 前缀
`.idEndsWith(text)`	ID 后缀
`.idMatches(pattern)`	ID Lua 模式匹配
`.text(text)`	文本完全匹配
`.textContains(text)`	文本包含
`.textStartsWith(text)`	文本前缀
`.textEndsWith(text)`	文本后缀
`.textMatches(pattern)`	文本 Lua 模式匹配
`.desc(desc)`	描述完全匹配
`.descContains(desc)`	描述包含
`.descStartsWith(desc)`	描述前缀
`.descEndsWith(desc)`	描述后缀
`.descMatches(pattern)`	描述 Lua 模式匹配
`.hint(text)`	提示文本
`.hintContains(text)`	提示文本包含
`.hintStartsWith(text)`	提示文本前缀
`.hintEndsWith(text)`	提示文本后缀
`.hintMatches(pattern)`	提示文本 Lua 模式匹配
`.type(className)`	元素类型

布尔约束

方法	说明
`.clickable(bool)`	可点击
`.longClickable(bool)`	可长按
`.scrollable(bool)`	可滚动
`.enabled(bool)`	可用
`.editable(bool)`	可编辑
`.focusable(bool)`	可聚焦
`.focused(bool)`	焦点状态
`.checkable(bool)`	可选中
`.checked(bool)`	选中状态
`.selected(bool)`	选择状态
`.visible(bool)`	可见状态

数值约束

方法	说明
`.index(n)`	结果索引（1 开始，负数从末尾）
`.depth(n)`	元素深度
`.childCount(n)`	子元素数量

配置方法

方法	说明
`.timeout(ms)`	等待超时（默认 0，最大 60000ms）
`.interval(ms)`	轮询间隔（默认 100ms，最小 10ms）
`.limit(n)`	限制 `all()` 返回数量

终结方法

方法	返回值	说明
`.get()`	Element/nil	获取第一个匹配
`.all()`	table	获取所有匹配（空时返回 `{}`）
`.exists()`	boolean	是否存在
`.count()`	number	匹配数量
`.waitUntilGone(ms)`	boolean	等待元素消失
`.debug()`	string	打印查询条件（调试用）

快捷方法

方法	返回值	说明
`.tryClick()`	boolean	找到则点击
`.tryLongClick()`	boolean	找到则长按
`.tryInput(text)`	boolean	找到则输入
`.tryClear()`	boolean	找到则清空
`.tryFocus()`	boolean	找到则聚焦

使用示例

基础查找

-- 查找链接
local link = node.webview():text("注册"):get()
if link then
    link:click()
end

-- 查找输入框
local input = node.webview():type("editText"):get()
if input then
    input:input("用户名")
end

等待元素

-- 等待按钮出现
local btn = node.webview():text("提交"):timeout(5000):get()
if btn then
    btn:click()
end

-- 等待加载完成
if node.webview():text("加载中"):waitUntilGone(10000) then
    print("加载完成")
end

使用快捷方法

-- 快捷写法
node.webview():text("登录"):tryClick()
node.webview():type("editText"):index(1):tryInput("用户名")
node.webview():type("editText"):index(2):tryInput("密码")
node.webview():text("提交"):tryClick()

调试查询

local q = node.webview():text("按钮"):clickable()
print(q:debug())
-- 输出: WebViewQuery{text="按钮", clickable=true}

与 App Query 的区别

特性	App Query	WebView Query
入口方法	`node.app()`	`node.webview(n)`
查询范围	整个控件树	指定 WebView 内
元素类型	Android 控件	DOM 映射元素
API 接口	相同	相同
Element 类型	相同	相同

注意事项

WebView 必须已加载 - 查询前确保 WebView 内容已渲染
动态内容 - H5 页面可能有动态加载，使用 timeout() 等待
DOM 映射 - 不是所有 HTML 元素都会暴露给 AccessibilityService
无 CSS/XPath - 只能使用 text/desc/id 等属性查询

概述​

创建查询器​

node.webview()​

约束方法​

字符串约束​

布尔约束​

数值约束​

配置方法​

终结方法​

快捷方法​

使用示例​

基础查找​

等待元素​

使用快捷方法​

调试查询​

与 App Query 的区别​

注意事项​

概述