List icon 目录

设计

本文档概述了该库的设计并指定了一般规则,以帮助您了解如何使用该库。

对象

所有的库对象可以分为两类:服务对象和不可变数据对象。服务对象允许执行一些操作,而数据对象只是存储数据。服务对象可能会使用数据对象。

EngineProfileBrowserBrowserSettingsFrameDocumentJsObject 这样的对象是服务对象。像 EngineOptionsSizeRect 这样的对象是不可变数据对象。

实例化

要创建不可变数据对象或服务对象,请使用其静态方法之一。例如:

Java
Kotlin
EngineOptions options = 
        EngineOptions.newBuilder(RenderingMode.HARDWARE_ACCELERATED)
                .language(Language.ENGLISH_US)
                .build();
Engine engine = Engine.newInstance(options);
val options = EngineOptions.newBuilder(RenderingMode.HARDWARE_ACCELERATED)
        .language(Language.ENGLISH_US)
        .build()
val engine = Engine.newInstance(options)

销毁

每个需要手动处理的服务对象都实现了 Closable 接口。要处理服务对象并释放所有分配的内存和资源,请调用 Closable.close() 方法。例如:

Java
Kotlin
engine.close();
engine.close()

一些服务对象如 Frame 可以自动处理,例如,当网页被卸载时。

任何使用已关闭对象的尝试都将导致 IllegalStateException

关联

服务对象的生命周期可能取决于另一个对象的生命周期。当您处理一个服务对象时,所有依赖它的服务对象都会自动处理。

例如,当您关闭 Engine 时,它的所有 Browser 实例都会自动关闭。当您关闭 Browser 时,它的所有 Frame 实例都会自动关闭。

方法

不返回任何值的方法是异步执行的。如果该方法返回某个值,则它将同步执行,阻塞当前线程执行,直到收到返回值。

如果该方法可以返回 null,其返回值将被包装成 java.util.Optional。例如:

Java
Kotlin
Optional<Frame> mainFrame = browser.mainFrame();
val mainFrame: Optional<Frame> = browser.mainFrame()

参数

所有输入参数都是非空的。如果将 null 作为输入参数传递给方法,该方法将抛出 NullPointerException。例如:

Java
Kotlin
Engine engine = Engine.newInstance(null); // <- NullPointerException
val engine = Engine.newInstance(null) // <- NullPointerException

事件

一个允许注册事件观察者的服务对象实现了 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()

回调

每个允许注册回调的对象都实现了 com.teamdev.jxbrowser.callback.Advisable 接口。要注册和注销回调,必须使用 set(Class<C> callbackClass, C callback)remove(Class<C> callbackClass) 方法。

回调可以是异步的,也可以是同步的。

异步

以下示例演示了如何通过给定的 tell 参数注册和注销一个异步回调,该回调异步返回响应:

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 将一直等待响应直到终止。

该响应只能提供一次。

同步

以下示例演示了如何注册和取消注册同步回调,该回调通过返回值返回响应:

Java
Kotlin
browser.set(CreatePopupCallback.class, params -> 
        CreatePopupCallback.Response.create());
browser.remove(CreatePopupCallback.class);
browser.set(CreatePopupCallback::class.java, CreatePopupCallback { 
        CreatePopupCallback.Response.create() 
})
browser.remove(CreatePopupCallback::class.java)

异常

该库仅抛出运行时异常,不抛出已检查异常。请查看每个方法的 Javadoc,以了解在何种情况下可能会抛出哪些异常。

线程安全

该库是线程安全的:可以在不同线程中安全地使用 JxBrowser 对象。