批注控件模式

介绍实现 IAnnotationProvider的准则和约定，包括有关属性和方法的信息。 批注 控件模式用于公开文档中批注的属性。

一个示例是位于文档边距中的批注框，并连接到某些文档文本或电子表格单元格。

下图显示了批注的示例。 有关实现此控件模式的控件示例，请参阅 控件类型及其支持的控件模式。

显示文档

本主题包含以下部分。

• 实施准则和约定
• IAnnotationProvider的 必需成员
• 相关主题

实施准则和约定

实现 批注 控件模式时，请注意以下准则和约定：

• 有许多不同类型的批注。 UIAutomationClient.h 头文件定义了一组命名的常量值，这些常量值标识Microsoft UI 自动化支持的批注类型。 有关详细信息，请参阅 批注类型标识符。
• 如果使用 AnnotationType_Unknown，则必须实现 IAnnotationProvider：：AnnotationTypeName 属性，使客户端能够发现批注类型的名称。 无需为标准批注类型实现 AnnotationTypeName，因为 UI 自动化提供了默认名称，但如果需要重写默认名称，则可以实现它。
• IAnnotationProvider：：Author 属性是可选的。
• IAnnotationProvider：:D ateTime 属性是可选的。
• IAnnotationProvider：：Target 属性是必需的，因为它将批注链接到 UI 元素，使客户端能够从批注导航回批注引用的 UI 元素。
• 由于批注可以采用许多不同的形式，因此 IAnnotationProvider 接口未定义用于存储批注的值或文本的属性。 简单的批注应公开 IValueProvider 接口，IValueProvider：：Value 属性应返回一个指定批注文本的只读值。 更丰富的批注应公开 ITextProvider 接口，以便向客户端提供更丰富的文本。
• 从 UI 元素导航到元素上的批注取决于要批注的元素类型，如下所示：
  • 对于电子表格单元格，实现 ISpreadsheetItemProvider：：GetAnnotationObjects 方法来引用批注。
  • 对于文本内容，在 ITextRangeProvider 接口上实现 AnnotationObjects 文本属性来引用批注。
• 某些类型的批注不需要完全实现 IAnnotationProvider 接口。 例如，一个简单的拼写错误指示器可以通过 ITextRangeProvider 接口返回 AnnotationType_SpellingError的 AnnotationTypes 文本属性，以及 AnnotationObjects 文本属性的 null 值来表示。
• 在不可见的 UI 元素上实现 IAnnotationProvider 接口非常有用。 例如，可以创建一个非可见的 UI 自动化元素，该元素实现 IAnnotationProvider，以提供有关语法错误的扩展信息。
• 如果控件包含重叠的注释，则基于文本的控件中的注释可能比较复杂。 使用以下准则来处理复杂批注：
  • 没有批注的文本范围应为 AnnotationTypes 文本属性返回空数组，并为 AnnotationObjects 文本属性返回空数组。
  • 具有一个批注的文本范围应为 AnnotationTypes 文本属性返回一个整数值的数组，并为 AnnotationObjects 文本属性返回一个 IRawElementProviderSimple 接口的数组。
  • 具有多个批注的文本范围应返回 AnnotationTypes 文本属性的多个整数值的数组，以及 AnnotationObjects 文本属性的匹配数量的匹配数量的 IRawElementProviderSimple 接口的数组。
  • 具有不同批注的文本范围（如带批注和非批注文本的区域）应返回 AnnotationTypes 和 AnnotationObjects的 ReservedMixedAttributeValue 属性。 接收此响应的客户端可以细分文本范围，以查找批注开始和结束的位置。

IAnnotationProvider 的必需成员

实现 IAnnotationProvider 接口需要以下属性。

此控件模式没有关联的事件。

相关主题

控件类型及其支持的控件模式

UI 自动化控件模式概述

UI 自动化树概述