List icon 目录

主要变更

API 与架构

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

请查看映射部分,了解 6.x 版本的主要功能如何映射到 7.0 版本。

系统要求

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

JARs

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

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

基本概念

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

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

Java
Kotlin
Engine engine = Engine.newInstance(options);
val engine = Engine.newInstance(options)

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

Java
Kotlin
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() 方法。例如:

Java
Kotlin
browser.close();
browser.close()

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

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

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

事件

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

6.x

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

Java
Kotlin
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)

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

Java
Kotlin
browser.removeTitleListener(titleListener);
browser.removeTitleListener(titleListener)

7.0

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

Java
Kotlin
Subscription subscription = browser.on(TitleChanged.class, event -> {});
...
subscription.unsubscribe();
val subscription = browser.on(TitleChanged::class.java) { event -> }
...
subscription.unsubscribe()

回调

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

6.x

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

Java
Kotlin
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) 方法。例如:

Java
Kotlin
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 参数返回结果,否则 Engine 将阻塞等待直到终止。

线程安全

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

许可

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

6.x

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

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

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 JREs 1.6 和 1.7、Apple 和 IBM 的 JREs、macOS 10.9 以及 OSGi

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

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