List icon 目录

设计

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

对象

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

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

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

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)

线程

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

Go Top