设计

这份文档概述了库的设计，同时提供了通用规则，以帮助你理解如何与其进行交互。

对象

所有库对象可分为以下类别：

• 服务对象；
• 不可变数据对象。

服务对象允许在数据对象只保存数据时执行一些操作。 服务对象可以使用数据对象。

像 IEngine, IBrowser, IProfile IBrowserSettings, IFrame, IDocument, IJsObject 实例都是 服务对象。 而 EngineOptions, Size, Rectangle 则是 不可变数据对象。

实例化

要创建不可变数据对象或服务对象，请使用其构造函数、构建器或其静态方法之一。 以下是使用构建器的示例：

EngineOptions options = new EngineOptions.Builder 
{
    RenderingMode = RenderingMode.HardwareAccelerated,
    Language = Language.EnglishUs
}.Build();
IEngine engine = EngineFactory.Create(options);

Dim options As EngineOptions = New EngineOptions.Builder With 
{
    .RenderingMode = RenderingMode.HardwareAccelerated,
    .Language = Language.EnglishUs
}.Build()
Dim engine As IEngine = EngineFactory.Create(options)

销毁

每个必须手动处理的服务对象都实现了 IDisposable 接口。 要处理服务对象并释放所有已分配的内存和资源，请调用 IDisposable.Dispose()方法。 例如：

engine.Dispose();

engine.Dispose()

诸如 IFrame 这样的一些服务对象可以自动释放，比如当网页被卸载时。 这些对象实现了 IAutoDisposable 接口。

如果您使用已处理的对象，则会发生ObjectDisposedException 。

关系

服务对象的生命周期可以依赖于另一个对象的生命周期。 当该服务对象被处理时，依赖于该服务对象的所有服务对象将被自动释放。 例如:

• 当您处理 IEngine时，它的所有 IBrowser 实例都会自动释放；
• 当您处理 IBrowser时，它的所有 IFrame 实例都会自动处理。

方法

返回 Task<T> 实例的方法是异步执行的。 如果该方法返回某个值，它会同步执行，阻塞当前线程执行，直到收到返回值。

处理程序

每个允许注册处理程序的对象都具有 IHandler<in T> 或 IHandler<in T, out TResult> 接口类型的属性。 要注册和注销处理程序，请使用属性设置器和获取器。

IHandler<in T, out TResult> 接口有默认实现：

• Handler<T, TResult> 类允许包装 lambda 和方法组；
• AsyncHandler<T, TResult> 类允许包装异步 lambda 和方法组或返回 Task<TResult> 的 lambda 和方法组。

异步

下面的示例演示了如何注册一个返回Task 以异步提供响应的异步处理程序：

browser.ShowContextMenuHandler =
    new AsyncHandler<ShowContextMenuParameters, ShowContextMenuResponse
    >(ShowContextMenu);

// 在相同类中声明的异步方法。
private async Task<ShowContextMenuResponse> ShowContextMenu(ShowContextMenuParameters p)
{
    // ...
}

browser.ShowContextMenuHandler = 
    New AsyncHandler(Of ShowContextMenuParameters, ShowContextMenuResponse)(
        AddressOf ShowContextMenu)

' 在相同类中声明的异步方法。
private async Task(Of ShowContextMenuResponse) ShowContextMenu(ShowContextMenuParameters p)
{
    ' ...
}

任务结果可以从不同的线程异步提供。

通过返回的 Task 参数提供响应，否则 IEngine 将等待响应直到终止。

同步

下面的示例演示了如何注册和注销通过返回值返回响应的常规 Handler ：

browser.CreatePopupHandler =
    new Handler<CreatePopupParameters, CreatePopupResponse>(p =>
    {
        return CreatePopupResponse.Create();
    });

browser.CreatePopupHandler = 
    New Handler(Of CreatePopupParameters, CreatePopupResponse)(Function(p)
        Return CreatePopupResponse.Create()
    End Function)

线程

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