AngleSharp API 文档

核心 API

AngleSharp 被设计为一个既实用又遵循标准的 API。如果你只关心解析单个文档或样式表，那么你可以直接使用各种解析器，如 HtmlParser 或 CssParser。在大多数情况下（解析和使用网页），我们推荐使用位于 AngleSharp 命名空间中的 BrowsingContext。这个命名空间也包含一些具有扩展方法的类型。

配置

IConfiguration 是扩展 AngleSharp 的主要接口。如果我们不关心，我们不必为解析文档或 URL 向 AngleSharp 提供 IConfiguration 实例。在这种情况下，将考虑默认配置。

这个默认配置可以通过调用 Configuration 类的 SetDefault 方法来选择。我们只需要传入自定义配置的实例以用作默认配置。Configuration 类是 IConfiguration 接口的默认实现。默认实现通常是提供自定义配置的良好起点。

IConfiguration 对象的作用是在需要时为浏览上下文提供服务的枚举。而这些服务则扩展了 DOM，使其超越了一个主要静态的版本。

以下示例设置新 IConfiguration 对象的 Culture：

var config = Configuration.Default.WithCulture("de-de");

如果不指定 Culture，将采用当前活动线程的文化。

请注意，默认情况下 Configuration 是不可变的，所有扩展方法将要么返回当前实例（未修改）要么返回一个新对象（与最初传递的相比已修改）。

此外，我们可能创建自己的类，该类比不可变实现更方便且灵活。我们可以扩展默认实现，或者实现接口。但是，请注意，扩展方法实际上应该使使用 IConfiguration 变得相当简单和直接。

实现接口也是可能的，但这当然需要更多的工作，因为每个属性或方法都需要重新实现。然而，由于默认实现的属性不是 virtual 的，这可能是提供所需设置的唯一机会。一般来说，自己实现 IConfiguration 的理由应该很少。

扩展点

AngleSharp 计划创建一个在 .NET 世界中可访问且完全用托管代码编写的通用 HTML5 解析器。然而，某些应用程序可能希望超出解析器的功能。仅凭解析器本身，在创建 DOM 时将需要外界大量帮助。

为了向 AngleSharp 用户提供完整的 DOM 实现，AngleSharp 在 HTML5 解析器的基础上扩展了真正的 DOM 实现。然而，这再次带来了一些额外的依赖。例如，如果 HtmlAudioElement 应该从其源播放音频怎么办？当然，可以简单地围绕元素编写一个包装器，读取 Source 并监督变化。但随后这个包装器可能会与其他 DOM 部分不兼容（和/或行为不同）。

这种不一致性通过以接口形式定义此类外部行为来避免。实现此类接口的对象可能被注册以便在 AngleSharp 中使用。

本页将列出并解释各种扩展点。目前缺失（但计划中）的接口将被概述。

IStylingService

当遇到样式（包括 <link> 标签中的外部样式表）或脚本块时，AngleSharp 会尝试找到匹配的引擎。例如，IStylingService 的实现会查看提供的 MIME 类型，并返回关联的 IStyleEngine 对象或 null。如果遇到后者，将尝试另一个 IStylingService 对象，直到找到合适的引擎，或所有样式服务都已询问。同样的算法适用于 IScriptingService。这些服务仅描述工厂、享元存储库或绑定的功能。

AngleSharp 已经包含了轻量级 CSS 解析器（用于 CSS 选择器）。这是 AngleSharp 设计目标之一。此外，它也是必需的，因为（HTML）DOM 在某些点上与 CSS 紧密耦合。一个例子是 querySelector 和 querySelectorAll 方法。这些方法需要 CSS 解析器（或至少是一个 CSS 选择器解析器）。最终，将产生一个能够匹配特定元素的对象。

然而，HTML 浏览器可能知道或不知道除 CSS 以外的其他样式可能性。目前，默认使用 CSS（并且没有指定，例如，在 type 属性中指定 text/css）。但是，可以为某个（或多）种类型注册一个样式解析器。按照这种方式，也可以注册一个自定义的 CSS 解析器，覆盖当前提供的那个。

这方面的一个例子是官方的 AngleSharp.Css 库，它实现了完整的 CSSOM。

IScriptingService

AngleSharp 默认不提供脚本引擎。当然，任何 JavaScript 引擎都会是一个很好的补充，因为 JavaScript 是网络的编程语言。

然而，目前没有意图提供官方/集成的解决方案。包含在我们组织中的 AngleSharp.Scripting 项目是一个示例和实验性项目，旨在展示编写此类扩展是多么简单。在这里，我们可以开始考虑允许 C#作为脚本语言。这当然是可能的。借助 scriptcs 或其他任何解决方案，这将是一个很好的补充，也可能有所不同。从长远来看，AngleSharp 支持多种脚本引擎是非常棒的。

正式地，我们试图建立 AngleSharp.Js 作为解决方案。这是一个与核心分离的项目，需要高维护和大量努力。对此的任何参与都将受到高度赞赏。

ISpellCheckService

允许注册单独的拼写检查器。每个拼写检查器都以其文化注册，使其对网页或文本可能使用的文化敏感。

API 允许忽略某些单词，查询单词是否拼写正确或获取单词正确拼写的建议。目前 API 已经同步实现，但在将来可能会切换到一个更好的、完全异步的版本。

IResourceService

此扩展在各种接口中实现，见：

IAudioService，针对 HtmlAudioElement
IVideoService，针对 HtmlVideoElement
IImageService，针对 HtmlImageElement
IObjectService，针对 HtmlObjectElement

基本思想是确定所含资源的某些属性。IResourceInfo 特化的实现携带资源依赖信息，对于图像来说，这将是尺寸等信息。在 HtmlAudioElement 的情况下，完整的媒体控制器也会实现，允许播放媒体流。

在 HtmlObjectElement 的情况下，这直接导致插件的使用，如 Adobe Flash 或其他。显然，AngleSharp 核心不负责这些非常特殊化的任务。

INavigator

为给定的 IWindow 实例创建一个 INavigator 实例。INavigator 乍一看似乎很通用，但实际上它可以非常专业化到底层的 IWindow 实例，尤其是在访问媒体资源（如摄像头或麦克风）方面。

AngleSharp 不实现该接口，以便留出空间进行更合适和专业的实现。此外，之前描述的通过外部外设增强用户体验的能力似乎很有吸引力。

IHistory

IHistory 接口通常以创建者的形式从服务中检索。它描述了创建与浏览上下文相关联的新 DOM IHistory 对象的功能。

IWindow

有多个 DOM 元素可以以更专业和有用的方式实现。一个关键元素是 IWindow 实现。它并不直接需要，因为所有的 DOM 交互都涉及 IDocument，而 IDocument 不依赖于 IWindow。然而，特别是在脚本环境中，IWindow 实例扮演着非常重要的角色。

对于更高级的场景，如渲染，自定义实现 IWindow 接口显得尤为重要。因此，给定的服务让用户有能力注册自定义的 IWindow 创建器。请注意，目前这样的自定义创建器需要至少继承自 EventTarget（实现了 IEventTarget）。在未来，这一要求有望被取消。

ILoader

在 AngleSharp 中加载文档或资源可以完全定制。主要接口是 ILoader，它是两个更专门化加载器的基础。一个是 IDocumentLoader，另一个是 IResourceLoader。前者然后被用来在浏览上下文的上下文中加载真实的文档（因此每个 IBrowsingContext 最多有一个 IDocumentLoader），后者被用来在 IDocument 的上下文中加载资源。显然，我们最多需要一个 IResourceLoader 每个 IDocument。

这种架构有两个大优点：

责任被明确分开，每个上下文（主要或文档）都可以跟踪自己的请求。
很容易关闭资源加载（甚至针对特定元素），而不影响文档加载/表单提交。

还有一个叫做 BaseLoader 的基础实现。

高级概念

在 AngleSharp 的标准使用之外，还有一些其他高级内容。

属性

AngleSharp.Attributes命名空间还包含了用于装饰接口（以及枚举和委托）的属性。具体包括：

DomAccessorAttribute：用于定义特殊的访问器，如获取器、设置器或删除器。
DomHistoricalAttribute：用于标记已过时的状态。
DomDescriptionAttribute：用于存储 DOM 部件的描述字符串。
DomNoInterfaceObjectAttribute：声明一个类型仅为接口形式，即没有对象实现可用。
DomPutForwardsAttribute：设置相关对象中，输入应转发到的方法名称。
DomNameAttribute：表示原始 API 名称。

接口/DOM 对象的 API 已被调整，使其仍然是原始 DOM API（没有任何缺失），但命名和类型遵循.NET 规范，希望更易于使用。