WebView Element 控件对象

WebView 内 DOM 元素的控件对象

概述

WebView Element 与 App Element 共享相同的 API。当通过 WebView Query 获取到元素后，返回的 Element 对象具有相同的属性和方法。

统一接口

无论是 App 控件还是 WebView 内的 DOM 元素，都使用相同的 Element 接口，实现了 API 的统一性。

---

属性

基础属性

属性	类型	说明
.text	string	元素文本内容
.hint	string	提示文本
.desc	string	描述（content-description）
.id	string	元素 ID
.type	string	元素类型
.pkg	string	所属包名
.bounds	Rect	位置大小（屏幕坐标）

状态属性

属性	类型	说明
.clickable	boolean	可点击
.longClickable	boolean	可长按
.scrollable	boolean	可滚动
.enabled	boolean	可用
.editable	boolean	可编辑
.focusable	boolean	可聚焦
.focused	boolean	焦点状态
.checkable	boolean	可选中
.checked	boolean	选中状态
.selected	boolean	被选择
.visible	boolean	可见

结构属性

属性	类型	说明
.childCount	number	子元素数量
.depth	number	树深度
.index	number	在父元素中的索引（从 0 开始）

---

关系方法

方法	返回值	说明
:parent()	Element/nil	父元素
:children()	table	所有直接子元素（空时返回 {}）
:child(n)	Element/nil	第 n 个子元素（1 开始）
:next()	Element/nil	下一个兄弟
:prev()	Element/nil	上一个兄弟
:sibling(n)	Element/nil	第 n 个兄弟（相对偏移）
:query()	Query	在此元素内创建查询器

---

动作方法

所有动作方法返回 boolean, string?，第二个值为失败原因。

点击操作

local ok, err = elem:click()
local ok, err = elem:doubleClick()
local ok, err = elem:longClick()

输入操作

local ok, err = elem:input("文本")   -- 输入（会清空原有）
local ok, err = elem:append("追加")  -- 追加文本
local ok, err = elem:clear()         -- 清空

焦点操作

local ok, err = elem:focus()   -- 获取焦点
local ok, err = elem:blur()    -- 清除焦点

选择操作

local ok, err = elem:select()    -- 选中
local ok, err = elem:deselect()  -- 取消选中

滚动操作

local ok, err = elem:scrollUp()
local ok, err = elem:scrollDown()
local ok, err = elem:scrollLeft()
local ok, err = elem:scrollRight()
local ok, err = elem:scrollForward()
local ok, err = elem:scrollBackward()
local ok, err = elem:scrollIntoView()  -- 滚动使自身可见

展开/折叠

local ok, err = elem:expand()
local ok, err = elem:collapse()

其他操作

local ok, err = elem:dismiss()
local ok, err = elem:copy()
local ok, err = elem:cut()
local ok, err = elem:paste()
local ok, err = elem:setSelection(from, to)

错误字符串列表

错误字符串	含义
"element is stale"	元素已失效（页面已变化）
"action not supported"	元素不支持此动作
"service disconnected"	无障碍服务断开
"element not visible"	元素不可见（可能被遮挡）
"element not focusable"	元素不可聚焦
"element not editable"	元素不可编辑
"element not scrollable"	元素不可滚动
"scroll reached end"	滚动已到达边界

---

实用方法

方法	返回值	说明
:refresh()	boolean	刷新元素信息
:isValid()	boolean	元素是否仍有效
:screenshot()	Image/nil	截取元素区域
:dump()	table	获取元素子树结构
:toString()	string	调试信息字符串

---

使用示例

基础操作

-- 查找并点击链接
local link = node.webview():text("注册"):get()
if link then
    local ok, err = link:click()
    if not ok then
        print("点击失败:", err)
    end
end

表单填写

-- 填写登录表单
local inputs = node.webview():type("editText"):all()
if #inputs >= 2 then
    inputs[1]:input("username")
    inputs[2]:input("password")
end

-- 点击登录
node.webview():text("登录"):tryClick()

遍历元素

-- 获取所有链接
local links = node.webview():clickable():all()
for i, link in ipairs(links) do
    print(i, link.text, link.bounds.x, link.bounds.y)
end

元素关系

-- 获取父容器
local btn = node.webview():text("提交"):get()
if btn then
    local form = btn:parent()
    if form then
        -- 在表单内查找输入框
        local input = form:query():type("editText"):get()
    end
end

生命周期管理

local elem = node.webview():text("动态内容"):get()

-- 页面可能发生变化
sys.msleep(2000)

-- 检查元素是否仍有效
if elem and elem:isValid() then
    elem:click()
else
    -- 重新查找
    elem = node.webview():text("动态内容"):get()
end

---

与 App Element 的区别

特性	说明
API 接口	完全相同
属性集合	完全相同
动作方法	完全相同
生命周期	相同（页面变化可能导致失效）

统一设计

WebView Element 和 App Element 使用完全相同的接口，你不需要区分它们。这是设计原则"统一接口"的体现。

---

注意事项

1. H5 页面动态性 - 单页应用可能频繁更新 DOM，注意检查元素有效性
2. 异步加载 - 使用 timeout() 等待元素加载完成
3. 坐标系统 - bounds 返回的是屏幕坐标，可直接用于 node.tap()
4. iframe - 嵌套的 iframe 可能作为单独的 WebView 处理