设计
这份文档概述了库的设计,同时提供了通用规则,以帮助你理解如何与其进行交互。
对象
所有库对象可分为以下类别:
- 服务对象;
- 不可变数据对象。
服务对象允许在数据对象只保存数据时执行一些操作。 服务对象可以使用数据对象。
像 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)
线程
该库不是线程安全的,因此请避免同时从不同线程使用该库。