批注控件模式

介绍实现 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 text 属性以引用批注。
• 某些类型的注释不需要 完全实现 IAnnotationProvider 接口。 例如，可以通过让 ITextRangeProvider 接口返回 AnnotationTypes 文本属性 AnnotationType_SpellingError和 AnnotationObjects 文本属性的 null 值来表示简单的拼写错误指示器。
• 在不可见的 UI 元素上实现 IAnnotationProvider 接口可能很有用。 例如，可以创建一个不可见的 UI 自动化 元素，该元素实现 IAnnotationProvider 以提供有关语法错误的扩展信息。
• 如果控件包含重叠的注释，则基于文本的控件中的注释可能比较复杂。 使用以下准则处理复杂批注：
  • 没有批注的文本范围应返回一个空数组作为 AnnotationTypes 文本属性，并为 AnnotationObjects 文本属性返回一个空数组。
  • 对于 AnnotationTypes 文本属性，具有一个批注的文本范围应返回一个整数值的数组，并为 AnnotationObjects 文本属性返回一个 IRawElementProviderSimple 接口的数组。
  • 具有多个批注的文本范围应返回一个由 AnnotationTypes 文本属性的多个整数值构成的数组，以及 AnnotationObjects 文本属性的 IRawElementProviderSimple 接口数匹配的数组。
  • 具有不同批注的文本范围（如同时具有批注文本和非批注文本的区域）应返回 AnnotationTypes 和 AnnotationObjects 的 ReservedMixedAttributeValue 属性。 接收此响应的客户端可以细分文本范围，以查找批注的开始和结束位置。

IAnnotationProvider 的必需成员

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

必需的成员	成员类型	说明
AnnotationTypeId	属性	无。
AnnotationTypeName	属性	无。
作者	属性	无。
Datetime	属性	无。
目标	属性	无。

 

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

相关主题

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

UI 自动化控件模式概述

UI 自动化树概述