DOM
本指南描述了如何访问 DOM 文档、查找元素、修改 DOM 结构、模拟用户输入等。
概述
在 Browser
中加载的每个网页都有一个主 Frame
。Frame
本身可能有子 Frames。例如,当网页包含 IFRAME
元素时,需要使用 Frame
类来访问 DOM 和 JavaScript。
访问文档
每个 Frame
都有一个 DOM Document
。要访问 Document
,请使用 Frame.document()
方法:
frame.document().ifPresent(document -> {});
frame.document().ifPresent { document -> }
查找元素
您可以根据不同的条件在元素中查找 HTML 元素。以下示例演示了如何查找文档元素内的所有 DIV
元素:
document.documentElement().ifPresent(documentElement ->
documentElement.findElementsByTagName("div").forEach(element -> {}));
document.documentElement().ifPresent { documentElement ->
documentElement.findElementsByTagName("div").forEach { element -> } }
如果您只需要查找第一个 HTML 元素,请使用以下方法:
documentElement.findElementByTagName("div").ifPresent(element -> {});
documentElement.findElementByTagName("div").ifPresent { element -> }
以下是按不同条件搜索 HTML 元素的示例:
documentElement.findElementsById("<id>");
documentElement.findElementsByName("<attr-name>");
documentElement.findElementsByTagName("<tag-name>");
documentElement.findElementsByClassName("<attr-class>");
documentElement.findElementsById("<id>")
documentElement.findElementsByName("<attr-name>")
documentElement.findElementsByTagName("<tag-name>")
documentElement.findElementsByClassName("<attr-class>")
XPath
JxBrowser DOM API 允许使用 Node.evaluate(String expression)
评估 XPath 表达式。您可以使用以下代码评估特定 Node
范围内的 XPath 表达式:
try {
XPathResult result = node.evaluate("count(//div)");
} catch (XPathException e) {
// 无法评估给定的表达式。
}
try {
val result: XPathResult = node.evaluate("count(//div)")
} catch (e: XPathException) {
// 无法评估给定的表达式。
}
当库无法计算给定表达式时,该方法会抛出 XPathException
。
评估结果存储在 XPathResult
对象中。请确保结果包含预期的值类型,例如 Number
、Boolean
、String
、Node
,并提取该值本身:
if (result.isNumber()) {
double number = result.asNumber();
}
if (result.isNumber()) {
val number: Double = result.asNumber()
}
查询选择器
查找与指定选择器匹配的元素,如 #root
,请使用以下代码:
List<Element> elements = element.findElementsByCssSelector("#root");
val elements = element.findElementsByCssSelector("#root")
点上的节点
要在网页上找到特定点(例如 100x150 处)的 Node
,请使用以下方法:
PointInspection inspection = frame.inspect(Point.of(100, 150));
inspection.node().ifPresent(node -> {});
val inspection: PointInspection = frame.inspect(Point.of(100, 150))
inspection.node().ifPresent { node -> }
与元素交互
元素边界
您可以通过以下代码获取相对于当前 Document
视口左上角位置的 Element
的边界:
Rect rect = element.boundingClientRect();
val rect = element.boundingClientRect()
这种方法在元素具有 hidden
属性或其 CSS 样式包含 display: none;
语句时将返回一个空的 Rect
。
元素属性
Element
类提供的方法允许您获取、添加、删除或修改 HTML 元素属性。以下示例演示如何获取元素的所有属性,并打印其名称和值:
element.attributes().asMap().forEach((name, value) ->
System.out.println(name + ": " + value));
element.attributes().asMap().forEach { name, value ->
println("$name: $value")
}
以下示例演示如何添加/修改元素属性:
element.attributes().put("attrName", "attrValue");
element.attributes["attrName"] = "attrValue"
创建元素
DOM API 允许修改文档 DOM 结构。以下示例演示了如何创建和插入带有一些文本的 <p>
元素:
// 创建一个新的段落元素。
Element paragraph = document.createElement("p");
// 创建一个包含给定文本的文本节点。
Node text = document.createTextNode("Text");
// 将文本节点插入到段落元素中。
if (paragraph.appendChild(text)) {
// 将段落元素插入到所需的元素中。
boolean success = element.appendChild(paragraph);
}
// 创建一个新的段落元素。
val paragraph = document.createElement("p")
// 创建一个包含给定文本的文本节点。
val text = document.createTextNode("Text")
// 将文本节点插入到段落元素中。
if (paragraph.appendChild(text)) {
// 将段落元素插入到所需的元素中。
success = element.appendChild(paragraph)
}
关闭节点
具有 Node
对应物的 DOM 对象不会受到 Blink 垃圾回收机制的自动处理。默认情况下,我们会将这些对象保留在内存中,直到页面被卸载。
为了优化内存使用,您可以基于每个对象启用垃圾回收:
node.close();
node.close()
关闭 Node
会将相应的 Blink 对象标记为可回收对象,但不会立即释放该对象。在调用 close()
方法后,尝试使用 Node
将导致 ObjectClosedException
。
DOM 事件
每个 Node
都实现了 EventTarget
接口,该接口提供了用于注册 DOM 事件的方法。您可以注册 DOM 监听器来接收 DOM 事件,例如 click
、mousedown
、mouseup
、keydown
、load
、error
等。
以下示例演示了如何为文档 HTML 元素注册点击事件监听器:
document.documentElement().ifPresent(element ->
element.addEventListener(EventType.CLICK, event -> {
// 鼠标点击事件已被接收。
if (event instanceof MouseEvent) {
MouseEvent mouseEvent = (MouseEvent) event;
int clickCount = mouseEvent.clickCount();
}
}, false));
document.documentElement().ifPresent { element ->
element.addEventListener(EventType.CLICK, { event ->
// 鼠标点击事件已被接收。
if (event is MouseEvent) {
val clickCount = event.clickCount()
}
}, false
)
}
此外,JxBrowser 还允许您监听自定义 DOM 事件并访问其数据载荷。
// 创建自定义的 DOM 事件类型。
EventType eventType = EventType.of("MyEvent");
// 监听给定事件类型的事件。
element.addEventListener(eventType, event -> {
// 已收到 MyEvent 事件。
if (event instanceof CustomEvent) {
CustomEvent customEvent = (CustomEvent) event;
JsObject payload = customEvent.detail();
}
}, false);
// 创建自定义的 DOM 事件类型。
val eventType = EventType.of("MyEvent")
// 监听给定事件类型的事件。
element.addEventListener(eventType, { event ->
// 已收到 MyEvent 事件。
if (event is CustomEvent) {
val payload = event.detail<JsObject>()
}
}, false)
自动化
JxBrowser DOM API 提供了自动填写 Wed 表单所需的一切。本节介绍如何更新文本字段中的文本、选择复选框或单选按钮、在下拉列表中选择一个或多个选项、模拟单击等。
要使用 Web 表单控件,请使用 FormControlElement
接口。此接口允许检查控件是否启用,并修改其值。所有的表单控件,如 INPUT
、SELECT
、TEXTAREA
等都继承了这个接口。
输入
要使用 INPUT
元素,请使用 InputElement
接口。 它提供了检查输入类型和设置其值所需的所有方法。
文本、邮箱、密码
要用新值替换文本、邮箱或密码字段的默认值,请使用 InputElement.value(String)
方法。
例如,如果您的 Web 表单包含以下类型的 <input>
元素:
<input type="text" id="firstname" placeholder="名字">
<input type="email" id="email" placeholder="邮箱地址">
<input type="password" id="password" placeholder="密码">
您可以使用以下方法设置它们的值:
documentElement.findElementById("firstname").ifPresent(element ->
((InputElement) element).value("李白"));
documentElement.findElementById("email").ifPresent(element ->
((InputElement) element).value("me@company.com"));
documentElement.findElementById("password").ifPresent(element ->
((InputElement) element).value("Jkdl12!"));
documentElement.findElementById("firstname").ifPresent { element ->
(element as InputElement).value("李白")
}
documentElement.findElementById("email").ifPresent { element ->
(element as InputElement).value("me@company.com")
}
documentElement.findElementById("password").ifPresent { element ->
(element as InputElement).value("Jkdl12!")
}
复选框、单选按钮
要选中单选按钮或复选框,请使用 InputElement.check()
方法。
例如,如果您的 Web 表单包含以下类型的 <input>
元素:
<input type="checkbox" id="checkbox" value="记住我">
<input type="radio" id="radio" checked>
您可以使用以下方法选择/取消选择它们:
documentElement.findElementById("checkbox").ifPresent(element ->
((InputElement) element).check());
documentElement.findElementById("radio").ifPresent(element ->
((InputElement) element).uncheck());
documentElement.findElementById("checkbox").ifPresent { element ->
(element as InputElement).check()
}
documentElement.findElementById("radio").ifPresent { element ->
(element as InputElement).uncheck()
}
文件
<input>
元素中的 type=file
允许用户从其设备存储中选择一个或多个文件。JxBrowser 允许您通过编程方式选择文件并更新 <input type=file>
元素的值。
例如,如果您的 Web 表单包含一个 <input>
元素,如下所示:
<input type="file" id="avatar" accept="image/png, image/jpeg" multiple>
您可以使用以下方法通过编程选择所需的一个或多个文件:
documentElement.findElementById("avatar").ifPresent(element ->
((InputElement) element).file("file1.png", "file2.jpeg"));
documentElement.findElementById("avatar").ifPresent { element ->
(element as InputElement).file("file1.png", "file2.jpeg")
}
文本区
要在 <textarea>
元素中设置文本,例如:
<textarea id="details"></textarea>
请使用以下方法:
documentElement.findElementById("details").ifPresent(element ->
((TextAreaElement) element).value("一些文本..."));
documentElement.findElementById("details").ifPresent { element ->
(element as TextAreaElement).value("一些文本...")
}
选择 & 选项
要选择 SELECT
控件中的所有选项,例如:
<select id="fruits" multiple>
<option>苹果</option>
<option>橘子</option>
<option>菠萝</option>
<option>香蕉</option>
</select>
请使用以下方法:
documentElement.findElementById("fruits").ifPresent(element -> {
SelectElement selectElement = (SelectElement) element;
selectElement.options().forEach(optionElement ->
optionElement.select());
});
documentElement.findElementById("fruits").ifPresent { element ->
val selectElement = element as SelectElement
selectElement.options().forEach { it.select() }
}
使用这种方法,您可以只选择一个所需的选项。
模拟点击
要模拟鼠标点击某个元素,请使用以下方法:
element.click();
element.click()
当 click()
与受支持的元素(例如 <input>
)一起使用时,它会触发元素的点击事件。然后该事件会冒泡到文档树中更高层级的元素,并触发它们的点击事件。
分发事件
您可以使用EventTarget.dispatch(Event)
方法在指定的 EventTarget
上分发一个 Event
。
以下示例演示了如何在指定的元素上分发标准的 click
事件:
// 客户端和屏幕位置。
Point location = Point.of(10, 10);
// 创建具有所需选项的 MouseEvent。
MouseEvent mouseClickEvent = document.createMouseEvent(EventType.CLICK,
MouseEventParams.newBuilder()
// 主按钮按下。
.button(Button.MAIN)
.clientLocation(location)
.screenLocation(location)
.uiEventModifierParams(
UiEventModifierParams.newBuilder()
.eventParams(EventParams.newBuilder()
.bubbles(true)
.cancelable(true)
.build())
.build())
.build());
// 在目标元素上生成点击事件。
element.dispatch(mouseClickEvent);
// 客户端和屏幕位置。
val location = Point.of(10, 10)
// 创建具有所需选项的 MouseEvent。
val mouseClickEvent = document.createMouseEvent(EventType.CLICK,
MouseEventParams.newBuilder()
// 主按钮按下。
.button(Button.MAIN)
.clientLocation(location)
.screenLocation(location)
.uiEventModifierParams(
UiEventModifierParams.newBuilder()
.eventParams(EventParams.newBuilder()
.bubbles(true)
.cancelable(true)
.build())
.build())
.build())
// 在目标元素上生成点击事件。
element.dispatch(mouseClickEvent)
使用这种方法,您可以创建和分发各种 DOM 事件。此类事件通常称为合成事件,与 Browser
本身触发的事件相对。