文档

功能	Data URL	自定义方案
支持 JavaScript-Java 桥接	是	是
支持 `InjectJsCallback`	是	是
支持 `InjectCssCallback`	是	是
从 HTTP 加载 `<iframe>`	是	是
从文件系统加载 `<iframe>`	否	否
从 HTTP 加载图像	是	是
从文件系统加载图像	否	否
产生网络事件	否	是
产生导航事件	是	是
显示 PDF 和打印预览	是	是
在 `<iframe>` 中显示 PDF 和打印预览	是	是

Data URL

这种方法的思想是将所需的 HTML 转换为一个 base64 字符串，使用转换后的字符串生成 Data URI，然后加载此 URL，如下所示：

Java
Kotlin

var html = "<html><body>Hello</body></html>";
var base64Html = Base64.getEncoder().encodeToString(html.getBytes(UTF_8));
var dataUrl = "data:text/html;charset=utf-8;base64," + base64Html;
browser.navigation().loadUrl(dataUrl);

val html = "<html><body>Hello</body></html>"
val base64Html = Base64.getEncoder().encodeToString(html.toByteArray(UTF_8))
val dataUrl = "data:text/html;charset=utf-8;base64,$base64Html"
browser.navigation.loadUrl(dataUrl)

您也可以使用 Frame.loadHtml(String html) 方法，它会自动从给定的 HTML 生成 data URI。

Java
Kotlin

var html = "<html><body>Hello</body></html>";
browser.mainFrame().ifPresent(frame -> frame.loadHtml(html));

val html = "<html><body>Hello</body></html>"
browser.mainFrame?.loadHtml(html)

由于 Chromium 的限制，URL 字符串的长度不得超过 2MB。尝试加载超过此限制的 URL 字符串将被 Chromium 忽略。

自定义方案

另一种从字符串加载 HTML 的方法是基于 InterceptUrlRequestCallback。这个方法的思路是注册回调函数并拦截特定的 URL 请求，以 HTTP 响应的形式返回所需的 HTML。例如：

Java
Kotlin

InterceptUrlRequestCallback interceptCallback = params -> {
    if (params.urlRequest().url().endsWith("?hello")) {
        var bytes = "<html><body>Hello</body></html>".getBytes();
        var job = params.newUrlRequestJob(
            UrlRequestJob.Options
                .newBuilder(HttpStatus.OK)
                .addHttpHeader(HttpHeader.of("Content-Type", "text/html"))
                .build());
        job.write(bytes);
        job.complete();
        return InterceptUrlRequestCallback.Response.intercept(job);
    }
    return InterceptUrlRequestCallback.Response.proceed();
};

var options = EngineOptions.newBuilder(renderingMode)
    .addScheme(HTTP, interceptCallback)
    .build();
var engine = Engine.newInstance(options);
var browser = engine.newBrowser();
browser.navigation().loadUrl("http://load.html/?hello");

val interceptCallback = InterceptUrlRequestCallback { params ->
    if (params.urlRequest().url().endsWith("?hello")) {
        val bytes = "<html><body>Hello</body></html>".toByteArray()
        val options = UrlRequestJobOptions(
            status = HttpStatus.OK,
            headers = listOf(HttpHeader("Content-Type", "text/html"))
        )
        val job = params.newUrlRequestJob(options).apply {
            write(bytes)
            complete()
        }
        InterceptUrlRequestCallback.Response.intercept(job)
    } else {
        InterceptUrlRequestCallback.Response.proceed()
    }
}

val engine = Engine(renderingMode) {
    schemes.add(HTTP, interceptCallback)
}
val browser = engine.newBrowser()
browser.navigation.loadUrl("http://load.html/?hello")

以 ?hello 结尾的 URL 请求将被拦截，并在 Browser 中加载 <html><body>Hello</body></html> HTML。

重新加载

有几个选项可以重新加载当前加载的网页：

使用 HTTP 缓存重新加载：

Java
Kotlin

navigation.reload();

navigation.reload()

忽略 HTTP 缓存重新加载：

Java
Kotlin

navigation.reloadIgnoringCache();

navigation.reloadIgnoringCache()

使用 HTTP 缓存重新加载并检查重新发布：

Java
Kotlin

navigation.reloadAndCheckForRepost();

navigation.reloadAndCheckForRepost()

忽略 HTTP 缓存重新加载并检查重新发布：

Java
Kotlin

navigation.reloadIgnoringCacheAndCheckForRepost();

navigation.reloadIgnoringCacheAndCheckForRepost()

停止

使用 Navigation.stop() 方法取消任何挂起的导航或下载操作，并停止任何动态页面元素，如背景声音和动画。例如：

Java
Kotlin

navigation.stop();

navigation.stop()

后退和前进

JxBrowser 允许操作导航前进-后退历史列表。

当您创建一个 Browser 实例时，它默认导航到 about:blank 网页，因此导航前进-后退列表中总是有一个条目。

要加载前进-后退列表中的前一个位置，请使用以下方法：

Java
Kotlin

if (navigation.canGoBack()) {
    navigation.goBack();
}

if (navigation.canGoBack) {
    navigation.goBack()
}

要加载前进-后退列表中的下一个位置，请使用：

Java
Kotlin

if (navigation.canGoForward()) {
    navigation.goForward();
}

if (navigation.canGoForward) {
    navigation.goForward()
}

要导航到前进-后退列表中特定索引处的条目，请使用：

Java
Kotlin

if (index >= 0 && index < navigation.entryCount()) {
    navigation.goToIndex(index);
}

if (index >= 0 && index < navigation.entryCount()) {
    navigation.goToIndex(index)
}

您可以遍历前进-后退列表并获取每个导航条目的详细信息：

Java
Kotlin

for (int index = 0; index < navigation.entryCount(); index++) {
    var navigationEntry = navigation.entryAtIndex(index);
    System.out.println("URL: " + navigationEntry.url());
    System.out.println("Title: " + navigationEntry.title());
}

for (index in 0 until navigation.entryCount()) {
    val navigationEntry = navigation.entryAtIndex(index)
    println("URL: ${navigationEntry.url()}")
    println("Title: ${navigationEntry.title()}")
}

您可以通过删除记录项来修改后退/前进列表：

Java
Kotlin

// 返回前进/后退列表中的条目数量。
var entryCount = navigation.entryCount();
// 移除指定索引处的导航条目。
for (int i = entryCount - 2; i >= 0; i--) {
    var success = navigation.removeEntryAtIndex(i);
    System.out.println("A entrada de navegação no índice " + i +
        " foi removida com êxito? " + success);
}

// 返回前进/后退列表中的条目数量。
val entryCount = navigation.entryCount()
// 移除指定索引处的导航条目。
for (i in entryCount - 2 downTo 0) {
    val success = navigation.removeEntryAtIndex(i)
    println("A entrada de navegação no índice $i foi removida com êxito? $success")
}

筛选 URL

您可以决定是否应该忽略对特定 URL 的导航请求。

以下代码演示了如何忽略对所有以 https://www.google 开头的 URL 的导航请求：

Java
Kotlin

navigation.set(StartNavigationCallback.class, params -> {
    // 忽略以 "https://www.google" 开头的 URL 的导航请求
    if (params.url().startsWith("https://www.google")) {
        return StartNavigationCallback.Response.ignore();
    }
    return StartNavigationCallback.Response.start();
});

navigation.register(StartNavigationCallback { params ->
    // 忽略以 "https://www.google" 开头的 URL 的导航请求
    if (params.url().startsWith("https://www.google")) {
        StartNavigationCallback.Response.ignore()
    } else {
        StartNavigationCallback.Response.start()
    }
})

过滤资源

使用 BeforeUrlRequestCallback 回调，您可以确定是否应加载如 HTML、图像、JavaScript 或 CSS 文件、favicon（网站图标）等资源。默认情况下，所有资源都会被加载。要修改默认行为，请注册您自己的回调实现，在该实现中决定应取消或加载哪些资源。

以下示例演示了如何禁止加载所有图片：

Java
Kotlin

var network = engine.network();
network.set(BeforeUrlRequestCallback.class, params -> {
    if (params.urlRequest().resourceType() == IMAGE) {
        return BeforeUrlRequestCallback.Response.cancel();
    }
    return BeforeUrlRequestCallback.Response.proceed();
});

val network = engine.network
network.register(BeforeUrlRequestCallback { params ->
    if (params.urlRequest().resourceType() === IMAGE) {
        BeforeUrlRequestCallback.Response.cancel()
    } else {
        BeforeUrlRequestCallback.Response.proceed()
    }
})

导航事件

加载网页是一个复杂的过程，在此过程中会触发不同的导航事件。下图显示了加载网页时可能触发导航事件的顺序： Navigation Events Flow

加载开始

要在内容加载开始时获得通知，请使用 LoadStarted 事件。例如：

Java
Kotlin

navigation.on(LoadStarted.class, event -> {});

navigation.subscribe<LoadStarted> { event -> }

此事件对应于选项卡的微调器开始旋转的时刻。

加载结束

要在内容加载完成时获得通知，请使用 LoadFinished 事件。例如：

Java
Kotlin

navigation.on(LoadFinished.class, event -> {});

navigation.subscribe<LoadStarted> { event -> }

此事件对应于标签页的加载指示器停止旋转的时刻。

导航开始

要在导航开始时获得通知，请使用 NavigationStarted 事件。例如：

Java
Kotlin

navigation.on(NavigationStarted.class, event -> {
    var url = event.url();
    // 指示导航是否将在同一文档的范围内执行。
    var isSameDocument = event.isSameDocument();
});

navigation.subscribe<NavigationStarted> { event ->
    val url = event.url()
    // 指示导航是否将在同一文档的范围内执行。
    val isSameDocument = event.isSameDocument
}

导航停止

要在导航停止时获得通知，请使用 NavigationStopped 事件。例如：

Java
Kotlin

navigation.on(NavigationStopped.class, event -> {});

navigation.subscribe<NavigationStopped> { event -> }

当通过 Navigation.stop() 方法停止导航时会触发此事件。

导航重定向

要在导航被重定向到新的 URL 时获得通知，请使用 NavigationRedirected 事件。例如：

Java
Kotlin

navigation.on(NavigationRedirected.class, event -> {
    // 导航重定向的 URL。
    var url = event.destinationUrl();
});

navigation.subscribe<NavigationRedirected> { event ->
    // 导航重定向的 URL。
    val url = event.destinationUrl()
}

导航结束

要在导航完成时收到通知，请使用 NavigationFinished 事件。例如：

Java
Kotlin

navigation.on(NavigationFinished.class, event -> {
    var url = event.url();
    var frame = event.frame();
    var hasCommitted = event.hasCommitted();
    var isSameDocument = event.isSameDocument();
    var isErrorPage = event.isErrorPage();
    if (isErrorPage) {
        var error = event.error();
    }
});

navigation.subscribe<NavigationFinished> { event ->
    val url = event.url()
    val frame = event.frame()
    val hasCommitted = event.hasCommitted()
    val isSameDocument = event.isSameDocument
    val isErrorPage = event.isErrorPage
    if (isErrorPage) {
        val error = event.error()
    }
}

此事件在导航提交、中止或被新导航替换时触发。要知道导航是否已提交，请使用 NavigationFinished.hasCommitted()；要知道导航是否导致错误页面，请使用 NavigationFinished.isErrorPage()。

如果事件是因为导航已提交而被调用，则文档加载仍将继续进行。

该事件由同一文档（在同一文档的范围内）导航触发，例如片段导航或 window.history.pushState()/window.history.replaceState()，这些操作不会导致文档内容的变化。请使用 NavigationFinished.isSameDocument() 来检查它是否是同一个文档的导航。

Frame 加载完成

要在 Frame 中的内容加载完成时收到通知，请使用 FrameLoadFinished 事件。例如：

Java
Kotlin

navigation.on(FrameLoadFinished.class, event -> {
    var url = event.url();
    var frame = event.frame();
});

navigation.subscribe<FrameLoadFinished> { event ->
    val url = event.url()
    val frame = event.frame()
}

此事件对应于 Frame 中的内容被完全加载的时刻。

Frame 加载失败

要在 Frame 中的内容由于某种原因加载失败时收到通知，请使用 FrameLoadFailed 事件。例如：

Java
Kotlin

navigation.on(FrameLoadFailed.class, event -> {
    var url = event.url();
    var error = event.error();
});

navigation.subscribe<FrameLoadFailed> { event ->
    val url = event.url()
    val error = event.error()
}

Frame 文档加载完成

要在 Frame 中的文档加载完成时收到通知，请使用 FrameDocumentLoadFinished 事件。例如：

Java
Kotlin

navigation.on(FrameDocumentLoadFinished.class, event -> {
    var frame = event.frame();
});

navigation.subscribe<FrameDocumentLoadFinished> { event ->
    val frame = event.frame()
}

此时，延迟脚本（deferred scripts）已经执行，并且标记为 “document_end” 的内容脚本已经被注入到 Frame 中。

介绍

安装

指南

故障排除

导航

加载 URL

使用 POST 加载 URL

加载文档

加载 HTML