主要变更
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()
静态方法。例如:
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
参数返回结果,否则 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_AWT
和FXCanvas
桥接功能,允许将 Swing/JavaFXBrowserView
嵌入到 SWT UI 中。作为替代,请改用 7.7 版本中引入的 SWTBrowserView
。