Controller

interface Controller

WebView自动化控制器接口(异步版)。

提供了一套全面的API,用于以异步、非阻塞的方式与WebView中的网页内容进行交互。 所有方法都会立即返回一个 Deferred 对象,代表一个未来的计算结果。 你可以通过 .getOrigin().await() 等待结果,或在协程作用域中直接 await()

⚠️ 注意: 此接口中的所有方法都是非阻塞的,可以安全地在任何线程中调用。 框架内部会自动将耗时操作(如JS评估)切换到后台线程,并将结果调度回脚本线程。

Functions

Link copied to clipboard
abstract fun addCookie(scope: CoroutineScope, name: String, value: String, domain: String?, path: String): Deferred<Unit>

异步向当前网页作用域添加一个 Cookie。

Link copied to clipboard
abstract fun attributeContains(scope: CoroutineScope, xpath: String, attributeName: String, valueToContain: String): Deferred<Boolean>

异步检查由XPath指定的元素的HTML属性值是否包含指定的子字符串。 这对于检查class列表等非常有用。

Link copied to clipboard
abstract fun attributeEquals(scope: CoroutineScope, xpath: String, attributeName: String, expectedValue: String): Deferred<Boolean>

异步检查由XPath指定的元素的HTML属性值是否等于期望值。

Link copied to clipboard
abstract fun back(scope: CoroutineScope): Deferred<Boolean>

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

Link copied to clipboard
abstract fun blur(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步让由 XPath 指定的元素失去焦点 (Blur)。

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

异步处理文件选择。会先执行 action(例如点击上传按钮),然后等待WebView弹出文件选择器, 并使用 fileChooser 的返回结果来响应。

Link copied to clipboard
abstract fun clear(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步清空由XPath指定的输入框中的内容。

Link copied to clipboard

异步清空 LocalStorage 中的所有数据。

Link copied to clipboard

异步清空 SessionStorage 中的所有数据。

Link copied to clipboard
abstract fun clearSiteData(scope: CoroutineScope, url: String, loadFinished: (CoroutineScope) -> Deferred<Boolean>): Deferred<Boolean>

终极清理:使指定 URL 对应的网站“失忆”,就像第一次打开一样。 只影响指定网站,不会清除其他网站的数据。该方法会首先跳转到 url 指定的网址, 然后通过 loadFinished 等待网站加载成功或者失败

Link copied to clipboard
abstract fun click(scope: CoroutineScope, xpath: String): Deferred<Boolean>

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

Link copied to clipboard
abstract fun clickAt(scope: CoroutineScope, xpath: String, xOffset: Int, yOffset: Int): Deferred<Boolean>

异步在由 XPath 指定的元素的指定偏移位置执行点击。 坐标 (0,0) 代表元素的左上角。

Link copied to clipboard
abstract fun contextClick(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步模拟在指定元素上进行右键点击。

Link copied to clipboard
abstract fun copy(scope: CoroutineScope): Deferred<Boolean>

异步模拟复制操作。 尝试复制当前选中的文本到剪贴板。

Link copied to clipboard
abstract fun cut(scope: CoroutineScope): Deferred<Boolean>

异步模拟剪切操作。 尝试剪切当前选中的文本。

Link copied to clipboard

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

Link copied to clipboard
abstract fun deleteCookie(scope: CoroutineScope, name: String): Deferred<Unit>

异步删除指定名称的 Cookie。

Link copied to clipboard
abstract fun dispatchEvent(scope: CoroutineScope, xpath: String, eventName: String): Deferred<Boolean>

异步对指定元素强制分发 (Dispatch) 一个原生的 JavaScript 事件。

Link copied to clipboard
abstract fun doubleClick(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步模拟双击指定元素。

Link copied to clipboard
abstract fun downloadFile(scope: CoroutineScope, action: (CoroutineScope) -> Deferred<Boolean>, fileDownloader: (FileDownloaderParams) -> ScriptFile): Deferred<Boolean>

异步处理文件下载。会先执行 action(例如点击下载链接),然后等待WebView触发下载请求, 并将文件保存到 fileDownloader 指定的位置。

Link copied to clipboard
abstract fun dragAndDrop(scope: CoroutineScope, sourceXpath: String, targetXpath: String): Deferred<Boolean>

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

Link copied to clipboard
abstract fun evaluateJs(scope: CoroutineScope, url: String, repeatable: Boolean): Deferred<String?>

异步加载并执行网络中的JavaScript文件。

Link copied to clipboard
abstract fun evaluateJsFile(scope: CoroutineScope, file: ScriptFile, repeatable: Boolean): Deferred<String?>

异步执行本地存储的JavaScript文件。

Link copied to clipboard
abstract fun evaluateJsString(scope: CoroutineScope, script: String, repeatable: Boolean): Deferred<String?>

异步在当前上下文中执行一段自定义的JavaScript脚本。

Link copied to clipboard
abstract fun focus(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步让由 XPath 指定的元素获得焦点 (Focus)。

Link copied to clipboard
abstract fun forward(scope: CoroutineScope): Deferred<Boolean>

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

Link copied to clipboard

异步获取当前网页下所有 Cookie。

Link copied to clipboard
abstract fun getAttribute(scope: CoroutineScope, xpath: String, attributeName: String): Deferred<String?>

异步获取由XPath指定的元素的某个HTML属性值 (Attribute)。

Link copied to clipboard
abstract fun getCookie(scope: CoroutineScope, name: String): Deferred<String?>

异步获取指定名称的 Cookie 值。

Link copied to clipboard
abstract fun getCssValue(scope: CoroutineScope, xpath: String, propertyName: String): Deferred<String?>

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

Link copied to clipboard

异步获取当前WebView加载的URL。

Link copied to clipboard
abstract fun getElementCount(scope: CoroutineScope, xpath: String): Deferred<Int>

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

Link copied to clipboard
abstract fun getInnerHtml(scope: CoroutineScope, xpath: String): Deferred<String?>

异步获取由 XPath 指定的元素的内部 HTML 内容 (innerHTML)。

Link copied to clipboard

异步从 LocalStorage 中获取指定键的值。

Link copied to clipboard
abstract fun getOuterHtml(scope: CoroutineScope, xpath: String): Deferred<String?>

异步获取由 XPath 指定的元素及其所有子节点的 HTML 内容 (outerHTML)。

Link copied to clipboard

异步获取当前页面的完整HTML源代码。

Link copied to clipboard
abstract fun getProperty(scope: CoroutineScope, xpath: String, propertyName: String): Deferred<String?>

异步获取由XPath指定的元素的某个 DOM 属性值 (Property)。

Link copied to clipboard
abstract fun getRect(scope: CoroutineScope, xpath: String): Deferred<IntRect?>

异步获取元素相对于浏览器视口的位置和尺寸。

Link copied to clipboard
abstract fun getScreenRect(scope: CoroutineScope, xpath: String): Deferred<IntRect?>

异步获取元素相对于屏幕视口的位置和尺寸。

Link copied to clipboard

异步从 SessionStorage 中获取指定键的值。

Link copied to clipboard
abstract fun getTagName(scope: CoroutineScope, xpath: String): Deferred<String?>

异步获取由 XPath 指定的元素的标签名称。

Link copied to clipboard
abstract fun getTextContent(scope: CoroutineScope, xpath: String): Deferred<String?>

异步获取由XPath指定的元素的聚合文本内容 (textContent)。

Link copied to clipboard
abstract fun getTitle(scope: CoroutineScope): Deferred<String?>

异步获取当前页面的标题。

Link copied to clipboard
abstract fun hasAttribute(scope: CoroutineScope, xpath: String, attributeName: String): Deferred<Boolean>

异步检查由XPath指定的元素是否包含指定的HTML属性 (Attribute)。

Link copied to clipboard
abstract fun hasProperty(scope: CoroutineScope, xpath: String, propertyName: String): Deferred<Boolean>

异步检查由XPath指定的元素是否包含指定的DOM属性 (Property)。

Link copied to clipboard
abstract fun hover(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步模拟鼠标悬停 (Hover) 在由 XPath 指定的元素上。

Link copied to clipboard
abstract fun inputKey(scope: CoroutineScope, xpath: String, keySequence: String): Deferred<Boolean>

通过输入法通道 (InputConnection) 向指定元素发送按键序列或组合快捷键。

Link copied to clipboard
abstract fun inputText(scope: CoroutineScope, xpath: String, text: String): Deferred<Boolean>

异步在由XPath指定的输入框中输入文本。

Link copied to clipboard
abstract fun isClickable(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步检查由XPath指定的元素当前是否可点击(存在、可见且已启用)。

Link copied to clipboard
abstract fun isDisplayed(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步检查由XPath指定的元素是否在页面上可见。

Link copied to clipboard
abstract fun isEnabled(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步检查由XPath指定的元素是否已启用(即没有 'disabled' 属性)。

Link copied to clipboard
abstract fun isPresent(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步检查由XPath指定的元素是否存在于DOM中。

Link copied to clipboard
abstract fun isReadyForInput(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步检查由XPath指定的输入框或文本域是否准备好接收输入。 条件:元素存在、可见、已启用且非只读。

Link copied to clipboard
abstract fun isSelected(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步检查表单元素是否被选中。

Link copied to clipboard
abstract fun loadData(scope: CoroutineScope, data: String, mimeType: String?, encoding: String?): Deferred<Unit>

异步使用 'data' scheme URL 将给定的数据加载到此WebView中。

Link copied to clipboard
abstract fun loadDataWithBaseURL(scope: CoroutineScope, baseUrl: String?, data: String, mimeType: String?, encoding: String?, historyUrl: String?): Deferred<Unit>

异步将给定的HTML字符串加载到此WebView中,并允许您指定一个基础URL。

Link copied to clipboard
abstract fun loadUrl(scope: CoroutineScope, url: String, additionalHttpHeaders: Map<String, String>): Deferred<Unit>

异步使用额外的HTTP头加载指定的URL。

Link copied to clipboard
abstract fun navigateTo(scope: CoroutineScope, url: String): Deferred<Unit>

异步导航到指定的网址。

Link copied to clipboard
abstract fun pageDown(scope: CoroutineScope, bottom: Boolean): Deferred<Boolean>

将网页视图(WebView)向下滚动。

Link copied to clipboard
abstract fun pageUp(scope: CoroutineScope, top: Boolean): Deferred<Boolean>

将网页视图(WebView)向上滚动。

Link copied to clipboard
abstract fun paste(scope: CoroutineScope, text: String): Deferred<Boolean>

异步模拟粘贴操作。 将指定的文本粘贴到当前聚焦的元素或选区中。

Link copied to clipboard
abstract fun pressKey(scope: CoroutineScope, xpath: String, keySequence: String): Deferred<Boolean>

异步模拟在指定元素上按下单个按键或组合键。

Link copied to clipboard
abstract fun propertyEquals(scope: CoroutineScope, xpath: String, propertyName: String, expectedValue: Any): Deferred<Boolean>

异步检查由XPath指定的元素的DOM属性值是否等于期望值。

Link copied to clipboard
abstract fun reload(scope: CoroutineScope): Deferred<Unit>

异步刷新当前页面。

Link copied to clipboard

异步从 LocalStorage 中移除指定键。

Link copied to clipboard

异步从 SessionStorage 中移除指定键。

Link copied to clipboard
abstract fun scrollBy(scope: CoroutineScope, xpath: String, dx: Int, dy: Int): Deferred<Boolean>

将指定元素内部的内容从当前位置滚动指定的偏移量 (dx, dy)。

Link copied to clipboard
abstract fun scrollIntoView(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步将指定的元素滚动到可视区域内。

Link copied to clipboard
abstract fun scrollTo(scope: CoroutineScope, xpath: String, x: Int, y: Int): Deferred<Boolean>

将指定元素内部的内容滚动到绝对坐标 (x, y)。

Link copied to clipboard
abstract fun scrollWindowBy(scope: CoroutineScope, dx: Int, dy: Int): Deferred<Unit>

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

Link copied to clipboard
abstract fun scrollWindowTo(scope: CoroutineScope, x: Int, y: Int): Deferred<Unit>

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

Link copied to clipboard
abstract fun selectAllText(scope: CoroutineScope, xpath: String): Deferred<Boolean>

异步选中由XPath指定的输入框或文本域中的所有文本。 适用于 <input><textarea> 元素。

Link copied to clipboard
abstract fun selectByValue(scope: CoroutineScope, xpath: String, value: String): Deferred<Boolean>

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

Link copied to clipboard
abstract fun selectByVisibleText(scope: CoroutineScope, xpath: String, text: String): Deferred<Boolean>

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

Link copied to clipboard
abstract fun selectTextRange(scope: CoroutineScope, xpath: String, start: Int, end: Int): Deferred<Boolean>

异步选中由XPath指定的输入框或文本域中的指定范围的文本。 适用于 <input><textarea> 元素。

Link copied to clipboard
abstract fun sendKeys(scope: CoroutineScope, xpath: String, text: String): Deferred<Boolean>

异步在由XPath指定的输入框中输入文本。

Link copied to clipboard
abstract fun setAttribute(scope: CoroutineScope, xpath: String, attributeName: String, value: String): Deferred<Boolean>

异步设置由 XPath 指定的元素的 HTML 属性 (Attribute) 值。

Link copied to clipboard
abstract fun setInnerHtml(scope: CoroutineScope, xpath: String, html: String): Deferred<Boolean>

直接修改指定元素的内部 HTML 结构(innerHTML)。

Link copied to clipboard
abstract fun setLocalStorageItem(scope: CoroutineScope, key: String, value: String): Deferred<Unit>

异步在 LocalStorage 中设置键值对。

Link copied to clipboard
abstract fun setProperty(scope: CoroutineScope, xpath: String, propertyName: String, value: Any): Deferred<Boolean>

异步设置由 XPath 指定的元素的 DOM 属性 (Property) 值。

Link copied to clipboard
abstract fun setSessionStorageItem(scope: CoroutineScope, key: String, value: String): Deferred<Unit>

异步在 SessionStorage 中设置键值对。

Link copied to clipboard
abstract fun setTextContent(scope: CoroutineScope, xpath: String, text: String): Deferred<Boolean>

直接修改指定元素的文本内容。

Link copied to clipboard

异步截取由XPath指定的单个元素的图像。

Link copied to clipboard

异步获取WebView可视区域的截图。

Link copied to clipboard
abstract fun textContentContains(scope: CoroutineScope, xpath: String, textToContain: String): Deferred<Boolean>

异步检查由XPath指定的元素的聚合文本内容 (textContent) 是否包含期望的子字符串。

Link copied to clipboard
abstract fun textContentEquals(scope: CoroutineScope, xpath: String, expectedText: String): Deferred<Boolean>

异步检查由XPath指定的元素的聚合文本内容 (textContent) 是否完全等于期望的文本。

Link copied to clipboard
abstract fun triggerAttributeDownload(scope: CoroutineScope, xpath: String, attributeName: String): Deferred<Boolean>

异步获取指定元素的属性值(如 src, href),并针对该地址触发下载动作。

Link copied to clipboard

异步触发 WebView 的下载动作(即触发 Android 端的 DownloadListener)。

Link copied to clipboard
abstract fun waitForAttributeValue(scope: CoroutineScope, xpath: String, attributeName: String, expectedValue: String, timeout: Long): Deferred<Boolean>

异步等待由XPath指定的元素的某个HTML属性值等于期望值,直到超时。

Link copied to clipboard
abstract fun waitForClickable(scope: CoroutineScope, xpath: String, timeout: Long): Deferred<Boolean>

异步等待由XPath指定的元素变得可点击(存在、可见且已启用),直到超时。

Link copied to clipboard
abstract fun waitForEnabled(scope: CoroutineScope, xpath: String, timeout: Long): Deferred<Boolean>

等待指定 XPath 的元素变为可用状态(即 disabled 属性为 false)。

Link copied to clipboard
abstract fun waitForInputReady(scope: CoroutineScope, xpath: String, timeout: Long): Deferred<Boolean>

异步等待由XPath指定的输入框或文本域变得可供输入,直到超时。 条件:元素变得存在、可见、已启用且非只读。

Link copied to clipboard
abstract fun waitForPresent(scope: CoroutineScope, xpath: String, timeout: Long): Deferred<Boolean>

异步等待由XPath指定的元素出现在DOM中,直到超时。

Link copied to clipboard
abstract fun waitForText(scope: CoroutineScope, xpath: String, textToContain: String, timeout: Long): Deferred<Boolean>

异步等待由XPath指定的元素的文本内容包含期望的子字符串,直到超时。

Link copied to clipboard
abstract fun waitForVisible(scope: CoroutineScope, xpath: String, timeout: Long): Deferred<Boolean>

异步等待由XPath指定的元素变得可见,直到超时。