文档

Version:
8.12.2 7.44.2
List icon 目录
Close
介绍
指南

Browser

本指南描述了如何创建、使用和关闭 Browser。

请考虑阅读架构指南以便更好地理解 JxBrowser 架构是如何设计的，它提供了哪些主要组件，以及它是如何工作的。

创建 Browser

要创建新的 Browser 实例，请使用 Profile.newBrowser() 方法。例如：

Java
Kotlin

var browser = profile.newBrowser();


val browser = profile.newBrowser()

如果您使用 Engine.newBrowser() 则 Browser 将在默认 Profile 下创建。

Java
Kotlin

var browser = engine.newBrowser();


val browser = engine.newBrowser()

此方法执行以下操作：

  1. 创建新的 Browser 实例。
  2. 在其中加载 about:blank 网页并等待网页加载完成。

关闭 Browser

Browser 实例在一个单独的本机进程中运行，该进程分配了内存和系统资源，这些资源需要在不再需要时被释放。因此，当不再需要 Browser 实例时，应该通过 Browser.close() 方法关闭它以释放所有分配的内存和系统资源。例如：

Java
Kotlin

var browser = engine.newBrowser();
...
browser.close();


val browser = engine.newBrowser()
...
browser.close()

尝试使用已关闭的 Browser 实例将导致 IllegalStateException。

在以下情况下，Browser 实例会自动关闭：

  1. 当其 Engine 关闭或意外崩溃时。
  2. 当 Browser 是使用 window.close() 从 JavaScript 关闭的弹出窗口时。

要在 Browser 实例关闭时获得通知，请使用 BrowserClosed 事件。例如：

Java
Kotlin

browser.on(BrowserClosed.class, event -> {});


browser.subscribe<BrowserClosed> { event -> }

要检查 Browser 是否关闭，请使用 isClosed() 方法：

Java
Kotlin

var closed = browser.isClosed();


val closed = browser.isClosed

Browser 大小

默认情况下，Browser 大小为空。如果您想在网页上使用 DOM 或查找文本，请配置其大小。

要更新 Browser 的大小，请使用 resize(int width, int height)。例如：

Java
Kotlin

browser.resize(800, 600);


browser.resize(800, 600)

此方法通知 Chromium Browser 的大小已更改。Chromium 将更新加载网页的 DOM 布局并异步重绘其内容。因此，在方法返回后重新绘制网页可能需要一些时间。

用户代理

您可以覆盖默认的用户代理字符串并将 Browser 配置为使用自定义字符串。例如：

Java
Kotlin

browser.userAgent("<user-agent>");


browser.userAgent("<user-agent>")

要获取当前用户代理字符串，请使用：

Java
Kotlin

var userAgent = browser.userAgent();


val userAgent = browser.userAgent

User-Agent Client Hints

Apart from the user agent itself, you can override the User-Agent Client Hints. You can specify the various settings, such as:

  • Browser brands and versions;
  • Device form factor;
  • Full browser version;
  • Operating system platform;
  • Platform version;
  • CPU architecture;
  • Bitness of the architecture (32-bit or 64-bit);
  • Device model;
  • Mobile status to check whether the browser is running on a mobile device.
  • WoW64 detection to determine if a 32-bit browser is running on a 64-bit Windows OS.

To override the User-Agent Client Hints, use the following API:

Java
Kotlin

var data = UserAgentData.newBuilder()
    .addBrand(UserAgentBrand.create("MyBrand", "1"))
    .addBrand(UserAgentBrand.create("MyBrand2", "2"))
    .addFormFactor("MyFormFactor")
    .fullVersion("1.0")
    .platform("MyOS")
    .platformVersion("1.0")
    .architecture("x86")
    .bitness("32")
    .model("MyModel")
    .mobile(true)
    .wow64(true)
    .build();
browser.userAgentData(data);


val data = UserAgentData.newBuilder()
    .addBrand(UserAgentBrand.create("MyBrand", "1"))
    .addBrand(UserAgentBrand.create("MyBrand2", "2"))
    .addFormFactor("MyFormFactor")
    .fullVersion("1.0")
    .platform("MyOS")
    .platformVersion("1.0")
    .architecture("x86")
    .bitness("32")
    .model("MyModel")
    .mobile(true)
    .wow64(true)
    .build()
browser.userAgentData(data)

To get the current User-Agent Client Hints, please use:

Java
Kotlin

var userAgentData = browser.userAgentData();


val userAgentData = browser.userAgentData()

远程调试 URL

要获取在特定 Browser 实例中加载的网页的远程调试 URL，请使用以下方法：

Java
Kotlin

browser.devTools().remoteDebuggingUrl().ifPresent(url -> {});


val url = browser.devTools.remoteDebuggingUrl

仅当 Engine 配置了远程调试端口时，此方法才会返回有效的 URL。

鼠标和键盘事件

JxBrowser 提供的功能允许您通过以下回调来拦截发送到网页之前的鼠标和键盘事件：

  • EnterMouseCallback
  • ExitMouseCallback
  • MoveMouseCallback
  • MoveMouseWheelCallback
  • PressKeyCallback
  • PressMouseCallback
  • ReleaseKeyCallback
  • ReleaseMouseCallback
  • TypeKeyCallback

以下示例演示了如何抑制鼠标滚轮：

Java
Kotlin

browser.set(MoveMouseWheelCallback.class, params ->
    MoveMouseWheelCallback.Response.suppress()
);


browser.register(MoveMouseWheelCallback {
    MoveMouseWheelCallback.Response.suppress()
})

您可以使用这些回调来获取有关鼠标和键盘事件的通知，以便在您的应用程序中实现快捷键。或者，您可以抑制默认的快捷键，如 Windows 和 Linux 上的 Ctrl+C。例如：

Java
Kotlin

browser.set(PressKeyCallback.class, params -> {
    var event = params.event();
    var keyCodeC = event.keyCode() == KeyCode.KEY_CODE_C;
    var controlDown = event.keyModifiers().isControlDown();
    if (controlDown && keyCodeC) {
        return PressKeyCallback.Response.suppress();
    }
    return PressKeyCallback.Response.proceed();
});


browser.register(PressKeyCallback { params ->
    val event = params.event()
    val keyCodeC = event.keyCode() == KeyCode.KEY_CODE_C
    val controlDown = event.keyModifiers().isControlDown
    if (controlDown && keyCodeC) {
        PressKeyCallback.Response.suppress()
    } else {
        PressKeyCallback.Response.proceed()
    }
})

调度键盘事件

您可以模拟输入 Browser 的焦点 DOM 元素。

Java
Kotlin

var character = 'h';
var keyCode = KeyCode.KEY_CODE_H;
var keyPressed = KeyPressed.newBuilder(keyCode)
    .keyChar(character)
    .build();
var keyTyped = KeyTyped.newBuilder(keyCode)
    .keyChar(character)
    .build();
var keyReleased = KeyReleased.newBuilder(keyCode)
    .build();

browser.dispatch(keyPressed);
browser.dispatch(keyTyped);
browser.dispatch(keyReleased);


val character = 'h'
val keyCode = KeyCode.KEY_CODE_H
val keyPressed = KeyPressed(keyCode, char = character)
val keyTyped = KeyTyped(keyCode, char = character)
val keyReleased = KeyReleased(keyCode)
with(browser) {
    dispatch(keyPressed)
    dispatch(keyTyped)
    dispatch(keyReleased)
}

屏幕共享

一些网页可能希望启动屏幕共享会话。Chromium 内置了允许共享屏幕、应用程序窗口或网页的功能。在 7.20 版本中，库 API 得到了扩展，添加了允许以编程方式处理此类请求或仅显示标准的 Chromium 对话框供用户选择捕获源的功能。

要显示标准对话框，请使用以下方法：

Java
Kotlin

browser.set(StartCaptureSessionCallback.class, (params, tell) ->
    tell.showSelectSourceDialog()
);


browser.register(StartCaptureSessionCallback { params, tell ->
    tell.showSelectSourceDialog()
})

WebRTC Screen Sharing Dialog

如果您不想显示对话框并希望以编程方式处理请求，您始终可以以编程方式选择捕获源并启动会话：

Java
Kotlin

browser.set(StartCaptureSessionCallback.class, (params, tell) -> {
    CaptureSources sources = params.sources();
    CaptureSource screen = sources.screens().get(0);
    // 告诉 Browser 实例使用给定的捕获源（第一个完整屏幕）
    // 开始一个新的捕获会话。
    tell.selectSource(screen, AudioCaptureMode.CAPTURE);
});


browser.register(StartCaptureSessionCallback { params, tell ->
    val sources = params.sources()
    val screen = sources.screens().first()
    // 告诉 Browser 实例使用给定的捕获源（第一个完整屏幕）
    // 开始一个新的捕获会话。
    tell.selectSource(screen, AudioCaptureMode.CAPTURE)
})

要以编程方式停止会话，请使用 CaptureSessionStarted 事件。当启动新的捕获会话时，此事件将被触发。您可以随时获取捕获会话的引用并停止它。以下示例演示了如何在 5 秒钟内停止已启动的捕获会话：

Java
Kotlin

browser.on(CaptureSessionStarted.class, event -> {
    var captureSession = event.capture();
    new java.util.Timer().schedule(new TimerTask() {
        @Override
        public void run() {
            // 在 5 秒后停止捕获会话。
            captureSession.stop();
        }
    }, 5000);
});


browser.subscribe<CaptureSessionStarted> { event ->
    val captureSession = event.capture()
    Timer().schedule(5000) {
        // 在 5 秒后停止捕获会话。
        captureSession.stop()
    }
}

桌面通知

安全的 (HTTPS) 网页可以通过通知 API 向终端用户显示桌面通知。该 API 的设计旨在与跨不同平台的现有通知系统兼容。

如果网页不是安全的 (HTTPS)，通知将无法工作。

要显示桌面通知，您必须授予相应的权限：

Java
Kotlin

engine.permissions().set(RequestPermissionCallback.class, (params, tell) -> {
    if (params.permissionType() == PermissionType.NOTIFICATIONS) {
        tell.grant();
    } else {
        tell.deny();
    }
});


engine.permissions.register(RequestPermissionCallback { params, tell ->
    if (params.permissionType() == PermissionType.NOTIFICATIONS) {
        tell.grant()
    } else {
        tell.deny()
    }
})

一些平台需要额外的配置才能启用桌面通知。在 macOS 上，当 JxBrowser 首次启动时，将提示终端用户允许 Chromium 显示其通知。

Chromium Notifications Prompt macOS

另外，终端用户可以在 macOS 系统偏好设置（System Preferences） -> 通知中心（Notification Centre） 中启用/禁用 Chromium 的通知：

Notification Centre Chromium

禁用桌面通知

如果您的应用程序不需要显示通知，并希望避免在 macOS 上弹出授权提示，可以通过 --disable-features 启动参数完全禁用通知功能：

Java
Kotlin

var options = EngineOptions
        .newBuilder(HARDWARE_ACCELERATED)
        .addSwitch("--disable-features=NativeNotifications")
        .build();
var engine = Engine.newInstance(options);


val engine = Engine(HARDWARE_ACCELERATED) {
    switches = listOf(
        "--disable-features=NativeNotifications"
    )
}

设置

使用 BrowserSettings，您可以为单个 Browser 实例配置不同的内容设置。您可以禁用图像、插件、JavaScript、本地存储、应用程序缓存，允许运行不安全的内容，或允许 JavaScript 访问剪贴板等。

默认编码

要在网页上配置默认文本编码，请使用：

Java
Kotlin

// Set the encoding.
settings.defaultEncoding("UTF-8");

// Get the current encoding.
var encoding = settings.defaultEncoding();


settings.defaultEncoding = "UTF-8"

JavaScript

默认情况下，JavaScript 在网页上是启用的。如果您需要禁用 JavaScript，请使用以下命令：

Java
Kotlin

// Disable JavaScript.
settings.disableJavaScript();
// Enable JavaScript.
settings.enableJavaScript();

// Get the current JavaScript status.
var enabled = settings.isJavaScriptEnabled();


settings.javascriptEnabled = false

图像

如果您不需要在网页上显示图像以减少网络流量，那么您可以禁用图像：

Java
Kotlin

// Disable loading and showing images.
settings.disableImages();
// Enable loading and showing images.
settings.enableImages();

// Check the current images status.
var enabled = settings.isImagesEnabled();


settings.imagesEnabled = false

插件

您可以[过滤][guides-plugins-filtering-plugins]已安装的插件，但如果您只需要禁用网页上的所有插件，则可以使用以下方法：

Java
Kotlin

// Disable plug-ins.
settings.disablePlugins();
// Enable plug-ins.
settings.enablePlugins();

// Check the current plug-in's status.
var enabled = settings.isPluginsEnabled();


settings.pluginsEnabled = false

本地存储

默认情况下，本地 WebStorage 功能是启用的。若要禁用它，并防止 JavaScript 在本地存储中存储数据，请使用以下设置：

Java
Kotlin

// Disable the local storage.
settings.disableLocalStorage();
// Enable the local storage.
settings.enableLocalStorage();

// Check the current local storage status.
var enabled = settings.isLocalStorageEnabled();


settings.localStorageEnabled = false

滚动条

在获取网页的位图或在自助服务亭应用程序内部时，您可能希望隐藏网页上的滚动条。在这种情况下，请使用以下设置：

Java
Kotlin

// Hide scrollbars.
settings.hideScrollbars();
// Show scrollbars.
settings.showScrollbars();

// Get the current status of scrollbars.
var scrollbarsHidden = settings.scrollbarsHidden();


settings.scrollbarsHidden = true

调用该方法后，Browser 实例中加载的网页将不再显示滚动条。

显示模式

[display-mode][CSS-@media-display-mode] CSS 媒体特性定义了 Web 应用在常规 Browser、全屏模式、独立应用或其他方式中的显示方式。

要为 Browser 配置 display-mode，请使用以下代码：

Java
Kotlin

// Set the display mode.
settings.displayMode(DisplayMode.FULLSCREEN);

// Get the current display mode.
var displayMode = settings.displayMode();


settings.displayMode = DisplayMode.FULLSCREEN

这个设置会改变 CSS 中的值，并影响哪些 CSS 规则被应用。但请注意，这个设置并不会改变 Browser 如何显示网页。

换句话说，上述代码会激活 @media (display-mode: fullscreen) 媒体查询下的 CSS，但并不会将 Browser 切换至全屏模式。

DevTools

您可以在不配置远程调试端口的情况下以编程方式显示/隐藏 DevTools 窗口：

Java
Kotlin

browser.devTools().show();


browser.devTools.show()

DevTools 将显示在一个单独的窗口中：

DevTools Window