Controller

interface Controller

WebView自动化控制器接口。

提供了一套全面的API,用于以同步阻塞的方式与WebView中的网页内容进行交互。 该接口遵循“快速失败”原则:所有方法在成功时返回预期数据,在操作失败时(如找不到元素、超时等)则会直接抛出异常。

⚠️ 警告: 此接口中的所有方法均为阻塞操作,会暂停调用它们的线程, 直到操作完成或超时。因此,绝对禁止在UI主线程中调用这些方法, 否则将导致应用程序无响应(ANR)。请务必在后台线程(如 IO 调度器)中执行这些操作。

Functions

Link copied to clipboard
abstract fun addCookie(name: String, value: String, domain: String?, path: String)

向当前网页添加一个 Cookie。

Link copied to clipboard
abstract fun back()

导航到浏览历史中的上一页。

Link copied to clipboard
abstract fun chooseFiles(action: () -> Long, fileChooser: (FileChooserParams?) -> List<ScriptFile>)

选择文件,会先执行 action,然后将 fileChooser 作为选择结果返回

Link copied to clipboard
abstract fun clear(xpath: String)

清空由XPath指定的输入框中的内容。 此方法通过将元素的 value 属性设置为空字符串并触发 inputchange 事件来完成。

Link copied to clipboard
abstract fun clearLocalStorage()

清空 LocalStorage 中的所有数据。

Link copied to clipboard
abstract fun clearSessionStorage()

清空 SessionStorage 中的所有数据。

Link copied to clipboard
abstract fun click(xpath: String)

模拟用户点击由XPath指定的元素。

Link copied to clipboard
abstract fun contextClick(xpath: String)

模拟在指定元素上进行右键点击,以触发上下文菜单(context menu)。

Link copied to clipboard
abstract fun deleteAllCookies()

删除当前网页下的所有 Cookie。

Link copied to clipboard
abstract fun deleteCookie(name: String)

删除指定名称的 Cookie。

Link copied to clipboard
abstract fun doubleClick(xpath: String)

模拟双击指定元素。

Link copied to clipboard
abstract fun downloadFile(action: () -> Long, fileDownloader: (FileDownloaderParams) -> ScriptFile)

下载文件,会先执行 action, 然后将文件保存到 fileDownloader 返回值所指定的文件中

Link copied to clipboard
abstract fun dragAndDrop(sourceXpath: String, targetXpath: String)

模拟将一个元素拖拽到另一个元素上。

Link copied to clipboard
abstract fun evaluateJs(url: String, repeatable: Boolean): String?

加载并执行网络中的JavaScript文件,并同步等待其执行结果。

Link copied to clipboard
abstract fun evaluateJsFile(file: ScriptFile, repeatable: Boolean): String?

执行本地存储的JavaScript文件,并同步等待其执行结果。

Link copied to clipboard
abstract fun executeJsString(script: String): String?

在当前上下文(主文档或已切入的iframe)中执行一段自定义的JavaScript脚本。

Link copied to clipboard
abstract fun forward()

导航到浏览历史中的下一页。

Link copied to clipboard
abstract fun getAllCookies(): Map<String, String>

获取当前网页下所有 Cookie。

Link copied to clipboard
abstract fun getAttribute(xpath: String, attributeName: String): String?

获取由XPath指定的元素的某个HTML属性值 (Attribute)。 这是指在HTML源码中定义的属性。对于动态改变的状态(如输入框的当前值),请使用 getProperty

Link copied to clipboard
abstract fun getCookie(name: String): String?

获取指定名称的 Cookie 值。

Link copied to clipboard
abstract fun getCssValue(xpath: String, propertyName: String): String?

获取由XPath指定的元素的计算后CSS样式属性值。

Link copied to clipboard
abstract fun getCurrentUrl(): String?

获取当前WebView加载的URL。

Link copied to clipboard
abstract fun getElementCount(xpath: String): Int

获取所有匹配XPath的元素的数量。

Link copied to clipboard
abstract fun getLocalStorageItem(key: String): String?

从 LocalStorage 中获取指定键的值。

Link copied to clipboard
abstract fun getPageSource(): String?

获取当前页面的完整HTML源代码 (document.documentElement.outerHTML)。

Link copied to clipboard
abstract fun getProperty(xpath: String, propertyName: String): String?

获取由XPath指定的元素的某个 DOM 属性值 (Property)。 这与 getAttribute 不同,它获取的是元素在内存中的实时属性值。 例如,对于一个输入框,getAttribute("value") 获取的是HTML中的初始值,而 getProperty("value") 获取的是用户输入后的当前值。

Link copied to clipboard
abstract fun getRect(xpath: String): RectF?

获取元素相对于 浏览器视口(viewport) 的位置和尺寸。

Link copied to clipboard
abstract fun getSessionStorageItem(key: String): String?

从 SessionStorage 中获取指定键的值。

Link copied to clipboard
abstract fun getText(xpath: String): String?

获取由XPath指定的元素的聚合文本内容 (textContent)。 textContent 会获取该元素及其所有后代元素的文本,忽略CSS样式。

Link copied to clipboard
abstract fun getTitle(): String?

获取当前页面的标题 (document.title)。

Link copied to clipboard
abstract fun isDisplayed(xpath: String): Boolean

检查由XPath指定的元素是否在页面上可见。 一个元素被认为是可见的,必须满足以下所有条件:

Link copied to clipboard
abstract fun isPresent(xpath: String): Boolean

检查由XPath指定的元素是否存在于DOM中(不关心是否可见)。

Link copied to clipboard
abstract fun isSelected(xpath: String): Boolean

检查表单元素(如复选框、单选按钮、<option>)是否被选中。

Link copied to clipboard
abstract fun navigateTo(url: String)

导航到指定的网址。

Link copied to clipboard
abstract fun pressKey(xpath: String, keySequence: String)

模拟在指定元素上按下单个按键或组合键。 这对于提交表单、触发键盘快捷键或在复杂组件中导航非常有用。

Link copied to clipboard
abstract fun reload()

刷新当前页面。

Link copied to clipboard
abstract fun removeLocalStorageItem(key: String)

从 LocalStorage 中移除指定键。

Link copied to clipboard
abstract fun removeSessionStorageItem(key: String)

从 SessionStorage 中移除指定键。

Link copied to clipboard
abstract fun scrollBy(dx: Int, dy: Int)

将整个页面按指定的偏移量进行滚动。

Link copied to clipboard
abstract fun scrollIntoView(xpath: String)

将指定的元素滚动到浏览器的可视区域内,并尽量使其居中。

Link copied to clipboard
abstract fun scrollTo(x: Int, y: Int)

将整个页面滚动到指定的绝对坐标。

Link copied to clipboard
abstract fun selectByValue(xpath: String, value: String)

根据value属性选择<select>下拉列表中的选项。

Link copied to clipboard
abstract fun selectByVisibleText(xpath: String, text: String)

根据可见文本内容选择<select>下拉列表中的选项。

Link copied to clipboard
abstract fun sendKeys(xpath: String, text: String)

在由XPath指定的输入框中输入文本。 此方法会直接设置元素的 value 属性,然后触发 inputchange 事件,以模拟真实用户输入并确保页面上的JS框架(如React, Vue)能正确响应。 注意:此方法不会预先清空输入框,而是直接覆盖其内容。

Link copied to clipboard
abstract fun setLocalStorageItem(key: String, value: String)

在 LocalStorage 中设置键值对。

Link copied to clipboard
abstract fun setSessionStorageItem(key: String, value: String)

在 SessionStorage 中设置键值对。

Link copied to clipboard
abstract fun switchToDefaultContent()

从当前iframe(无论嵌套多深)切换回主文档上下文。

Link copied to clipboard
abstract fun switchToFrame(xpath: String)

切换到指定的iframe中。后续所有操作都将在此iframe的上下文中执行。 此操作可以嵌套,即可以从一个iframe切换到其内部的另一个iframe。

Link copied to clipboard
abstract fun takeElementScreenshot(xpath: String, file: ScriptFile): Boolean

截取由XPath指定的单个元素的图像,并将其保存到指定文件。 此方法会先将元素滚动到视图内(如果需要),然后截取其可视部分的图像。

Link copied to clipboard
abstract fun takeScreenshot(file: ScriptFile): Boolean

获取WebView 可视区域 的截图,并将其保存到指定文件。 注意:此方法仅截取当前屏幕上可见的部分,不会滚动截取整个长网页。

Link copied to clipboard
abstract fun waitForElementPresent(xpath: String, timeout: Long): Boolean

通过轮询检查,等待由XPath指定的元素出现在DOM中,直到超时。

Link copied to clipboard
abstract fun waitForElementVisible(xpath: String, timeout: Long): Boolean

通过轮询检查,等待由XPath指定的元素变得可见,直到超时。