主要变更

API 与架构

在 JxBrowser 7 中，库的架构得到了改进。现在，JxBrowser 允许您创建两个完全独立的 Browser 实例并控制它们的生命周期。随着这种内部架构的更改，公共 API 也得到了改进和扩展，引入了新的功能。

请参阅映射部分，了解 6.x 版本的主要功能如何映射到 7.0 版本。

系统要求

从该版本开始，JxBrowser 不再支持 Oracle JRE 1.6 和 1.7、Apple 和 IBM 的 JRE、macOS 10.9 以及 OSGi。当前系统要求可在此处查阅。

JAR

库的结构发生了变化。现在该库由以下 JAR 文件组成：

• jxbrowser-7.38.2.jar 核心类和接口；
• jxbrowser-swing-7.38.2.jar 用于嵌入 Swing 应用程序的类和接口；
• jxbrowser-javafx-7.38.2.jar 用于嵌入 JavaFX 应用程序的类和接口；
• jxbrowser-win32-7.38.2.jar 适用于 Windows 的 Chromium 32 位二进制文件；
• jxbrowser-win64-7.38.2.jar 适用于 Windows 的 Chromium 64 位二进制文件；
• jxbrowser-linux64-7.38.2.jar 适用于 Linux 的 Chromium 64 位二进制文件；
• jxbrowser-mac-7.38.2.jar 适用于 macOS 的 Chromium 二进制文件。

基本概念

在新的 API 中，创建和销毁对象的方式发生了变化。

要创建服务对象，请使用 <ServiceObject>.newInstance() 静态方法。例如：

Engine engine = Engine.newInstance(options);

val engine = Engine.newInstance(options)

要创建不可变数据对象，请使用 Object.newBuilder() 静态方法。例如：

EngineOptions engineOptions = EngineOptions.newBuilder(...)
        .setLanguage(Language.ENGLISH_US)
        .build();

val options = EngineOptions.newBuilder(...)
        .language(Language.ENGLISH_US)
        .build()

每个需要手动销毁的对象都实现了 com.teamdev.jxbrowser.Closable 接口，例如 com.teamdev.jxbrowser.Browser。要销毁对象，请调用 com.teamdev.jxbrowser.Closable.close() 方法。例如：

browser.close();

browser.close()

请注意，一些服务对象依赖于其他服务对象。当你销毁一个服务对象时，所有依赖于它的服务对象都将自动销毁，因此你无需手动关闭它们。有关关键对象及其交互原理的更多详细信息，请参阅架构指南。

如果一种方法可能返回 null，则其返回值将被包装到 java.util.Optional 中。例如：

browser.mainFrame().ifPresent(frame -> {});

browser.mainFrame().ifPresent { frame -> }

事件

注册事件监听器的方式已更改。

6.x 版本

我们使用经典的观察者模式，其中包含 addXxxListener(XxxListener listener) 和 removeXxxListener(XxxListener listener) 方法，允许您注册和注销事件监听器。例如：

TitleListener titleListener = new TitleListener() {
    @Override
    public void onTitleChange(TitleEvent event) {}
};
browser.addTitleListener(titleListener);

val titleListener = object: TitleListener { 
    override fun onTitleChanged(event: TitleEvent) {}
} 
browser.addTitleListener(titleListener)

当您不再希望接收事件通知时，应使用相应的方法来注销事件监听器：

browser.removeTitleListener(titleListener);

browser.removeTitleListener(titleListener)

7.0 版本

允许注册事件观察者的服务对象实现了 com.teamdev.jxbrowser.event.Observable 接口。要注册事件观察者，请使用 on(Class<E> eventClass, Observer<E> observer) 方法。此方法返回 Subscription。使用此实例来取消订阅所需的事件。例如：

Subscription subscription = browser.on(TitleChanged.class, event -> {});
...
subscription.unsubscribe();

val subscription = browser.on(TitleChanged::class.java) { event -> }
...
subscription.unsubscribe()

回调

注册事件处理器（回调）的逻辑也发生了变化。

6.x 版本

要注册事件处理器，请使用 setXxxHandler(XxxHandler handler) 方法来设置和移除事件处理器。例如：

browser.setDialogHandler(new DialogHandler() {
    ...
    @Override
    public CloseStatus onConfirmation(DialogParams params) {
        return CloseStatus.OK;
    }
    ...
});
browser.setDialogHandler(null);

browser.setDialogHandler(object: DialogHandler {  
    ...
    override fun onConfirmation(params: DialogParams): CloseStatus = CloseStatus.OK
    ...
})

7.0 版本

事件处理程序现在命名为回调（Callbacks）。每个允许注册回调的对象都实现了 com.teamdev.jxbrowser.callback.Advisable 接口。要注册和注销回调，应使用 set(Class<C> callbackClass, C callback) 和 remove(Class<C> callbackClass) 方法。例如：

browser.set(ConfirmCallback.class, (params, tell) -> tell.ok());
browser.remove(ConfirmCallback.class);

browser.set(ConfirmCallback::class.java, ConfirmCallback { params, tell -> tell.ok() })
browser.remove(ConfirmCallback::class.java)

请不要忘记通过给定的 tell 参数返回结果，否则引擎将处于阻塞状态，直到程序终止。

线程安全

该库不是线程安全的，因此请不要同时从不同线程使用该库。

许可

在 JxBrowser 7 中，许可证的格式和库检查许可证的方式都得到了改进。

6.x 版本

在之前的版本中，许可证是一个 JAR 文件（例如 license.jar），其中包含名为 teamdev.licenses 的文本文件。此文本文件包含许可证的纯文本。要设置许可证，您必须将此 JAR 文件包含在您 Java 应用程序的类路径中。

项目许可证绑定到完全限定的类名（例如 com.company.product.MyClass）。它可以是您应用程序的任何类。唯一的要求是此类必须包含在使用 JxBrowser 的 Java 应用程序的类路径中。

7.0 版本

现在，该库需要一个许可证密钥，该密钥是一个由字母和数字组成的字符串。您可以通过 jxbrowser.license.key 系统属性或通过 API 将许可证添加到您的项目中。

项目许可证现在与包名绑定。该包名应该采用 com.company.product.module 格式。它应该是您在其中创建 Engine 实例的类的顶级包。

例如，如果项目许可证与 com.company.product 包名绑定，则您只能在位于 com.company.product.* 包中的类中创建 Engine 实例。

Engine 是在 JxBrowser 7 中引入的。我们建议您查阅相关指南，以了解新架构的详情、如何创建 Engine 以及管理多个 Browser 的生命周期。

您可以在没有任何限制的情况下使用创建的 Engine 实例，并从位于其他包中的类调用库的API。

删除的功能

从该版本开始，JxBrowser 不再支持 Oracle JRE 1.6 和 1.7、Apple 和 IBM 的 JRE、macOS 10.9 以及 OSGi.

在新版本中，以下功能已被暂时删除。我们计划将在后续更新中提供替代方案：

• 对加载的网页进行截图。在 7.1 版本中恢复。
• 抑制鼠标和键盘事件。在 7.1 版本中恢复。
• 关闭 Browser 时显示 BeforeUnload 对话框。在 7.6 版本中恢复了在关闭 Browser 时显示对话框的可能性。了解更多。
• 在离屏渲染模式下的透明背景。在 7.2 版本中恢复。
• 在硬件加速（重量级）渲染模式下，macOS 上的 IME、辅助功能以及“双指缩放”功能。
• WebStorage API。 在 7.1 版本中恢复。
• SWT_AWT 和 FXCanvas 桥接功能，允许将 Swing/JavaFX BrowserView 嵌入到 SWT UI 中。作为替代，请改用 7.7 版本中引入的 SWT BrowserView。