使用 IUIAutomationTextRange 访问和操作文本区域

本主题介绍如何使用 IUIAutomationTextRange 接口的属性和方法访问和操作基于文本的控件的文本内容。

什么是文本范围？

Microsoft UI 自动化文本对象模型基于文本范围的概念。 文本范围是公开 IUIAutomationTextRange 接口的对象，表示基于文本的控件中的连续文本范围。 每个文本范围都有一个起始终结点和一个结束终结点，两个终结点之间的所有文本内容都被视为该范围的一部分。 起始终结点和结束终结点位于同一位置的文本范围称为 退化 (或文本范围空) 。 退化的文本范围用于标记控件文本中的特定位置，例如文本插入点的位置。

获取文本范围对象

客户端应用程序使用 IUIAutomationTextPattern 接口的属性和方法获取文本范围对象。 IUIAutomationTextRangePattern：:D ocumentRange 属性检索表示基于文本的控件的整个文本内容的文本范围，而其他方法则获取表示内容的某些部分（如所选文本、可见文本或嵌入在文本中的对象）的文本范围。

IUIAutomationTextRangePattern：：GetVisibleRanges 和 GetSelection 方法可以检索文本范围对象的数组。 如果控件被重叠窗口或其他对象部分遮盖， 则 GetVisibleRanges 将返回一个数组，其中包含每个部分可见文本行的文本范围对象。 同样，如果基于文本的控件支持选择多个不连续的文本范围， 则 GetSelection 将返回一个数组，其中包含每个选定范围的文本范围对象。

IUIAutomationTextRangePattern：：RangeFromChild 方法使客户端应用程序能够检索包含嵌入在文本内容中的对象的文本范围。 客户端指定嵌入对象（如图像、表或超链接）的 IUIAutomationElement 接口指针，该方法返回包含该对象的文本范围。 但是，如果嵌入对象没有与之关联的文本，该方法将返回退化的文本范围。

客户端应用程序可以使用 IUIAutomationTextRangePattern：：RangeFromPoint 方法检索最接近指定屏幕坐标的可见文本或嵌入对象的文本范围。

在文本范围内选择文本

IUIAutomationTextRange 接口包含许多方法，使客户端应用程序能够控制基于文本的控件中的文本选择。

客户端应用程序可以使用 IUIAutomationTextRange：：Select 方法选择与文本范围对应的文本，并从文本控件中删除上一个选择（如果有）。 调用 具有 退化文本范围的 Select 会将插入点移动到文本区域的位置，而不选择任何文本。

如果控件支持选择多个非连续文本范围，则客户端可以使用 IUIAutomationTextRange：：AddToSelection 和 RemoveFromSelection 方法将文本范围添加到所选文本范围的集合以及从中删除它们。 如果控件一次仅支持一个选定的文本范围，但选择操作将导致选择多个不连续文本范围，则该方法将返回 E_INVALIDOPERATION 错误，或者扩展或截断当前所选内容。 客户端应用程序可以通过检查 IUIAutomationTextPattern：：SupportedTextSelection 属性来发现控件是否支持选择单个或多个文本范围，或者根本不支持选择任何文本范围。

如果基于文本的控件支持文本插入，则对控件中退化的文本范围调用 IUIAutomationTextRange：：AddToSelection 或 RemoveFromSelection 将移动插入点，但不选择任何文本。

从文本范围检索文本

客户端应用程序可以使用 IUIAutomationTextRange：：GetText 方法检索文本范围的纯文本。 纯文本包括源文本中找到的所有控制字符，例如回车符和 Unicode 从左到右标记 (LRM) 。 纯文本不包括源文本中可能存在的任何标记，例如 HTML。 此外，源文本中的任何转义代码将转换为纯文本等效项。 例如，“”“转换为简单空格字符。

如果嵌入对象跨越一系列文本，则纯文本包括该对象的内部文本，但不包括嵌入对象) 的 name 属性 (可选文字。 有关详细信息，请参阅 UI 自动化如何公开嵌入对象。

IUIAutomationTextRange：：FindText 方法在文本范围内搜索特定字符串，如果找到该字符串，则返回包含该字符串的新文本范围。

从文本范围检索文本属性

文本属性确定基于文本的控件中文本的格式样式，并包括前景色、项目符号样式、字号等。 UI 自动化支持多个文本属性，并为每个受支持的属性定义标识符。 客户端应用程序可以在调用 IUIAutomationTextRange：：GetAttributeValue 方法时指定属性标识符，以及指向接收属性值的 VARIANT 结构的指针，从而查询特定文本属性的值的文本范围。 有关UI 自动化支持的每个文本属性的详细信息，请参阅文本属性标识符。

GetAttributeValue 检索的值表示整个文本范围内属性的值。 如果范围中的所有文本共享指定属性的相同值，则 GetAttributeValue 将返回该值。 但是，如果属性的值在文本范围内不同，则 GetAttributeValue 返回指向名为 ReservedMixedAttribute 对象的静态标记对象的 IUnknown 指针。 若要发现属性的值是否因文本范围而异，客户端应用程序应将 GetAttributeValue 的结果与从 IUIAutomation：：ReservedMixedAttributeValue 属性检索到的 ReservedMixedAttribute 对象进行比较。

无需基于文本的控件即可支持所有UI 自动化文本属性。 如果客户端调用 IUIAutomationTextRange：：GetAttributeValue 方法并传递不受支持的属性的标识符，则该方法返回指向名为 ReservedNotSupported 对象的静态令牌对象的 IUnknown 指针。 若要发现是否支持特定属性，客户端应用程序应将 GetAttributeValue 的结果与从 IUIAutomation：：ReservedNotSupportedValue 属性检索到的 ReservedNotSupported 对象进行比较。

客户端应用程序可以使用 IUIAutomationTextRange：：FindAttribute 方法在文本范围内搜索具有特定文本属性的文本。 如果找到，该方法将返回包含匹配文本的新文本范围。 请注意，即使文本不可见， FindAttribute 也会返回匹配文本的文本范围。

从文本范围检索嵌入对象

文本范围可以包含嵌入的对象，如表、图像、超链接等。 客户端应用程序可以通过调用 IUIAutomationTextRange：：GetChildren 方法检索范围中所有嵌入对象的集合。 与区域重叠但不完全封闭的嵌入对象也包含在集合中。 如果区域不包含嵌入的对象， GetChildren 将检索空集合。

尽管它依赖于基于文本的控件的提供程序， 但 GetChildren 方法通常不返回嵌入元素的任何子元素。 例如，如果文本区域包含具有多个子单元格的表， 则 GetChildren 方法通常只返回表元素，而不返回单元格元素。

出于性能或体系结构原因， GetChildren 可能无法检索文本范围中所有嵌入对象的 IUIAutomationElement 对象。 相反，提供程序可能会返回包含虚拟化项的集合。 有关详细信息，请参阅 使用虚拟化项。

操作文本区域

IUIAutomationTextRange 接口提供了多种方法，用于在基于文本的控件中操作和导航文本范围。 IUIAutomationTextRange：：Move、MoveEndpointByUnit 和 ExpandToEnclosingUnit 方法按指定的文本单位（如字符、单词、段落等）移动文本范围或其终结点之一。 有关详细信息，请参阅UI 自动化文本单位。

尽管具有名称， 但 ExpandToEnclosingUnit 方法不一定扩展文本范围。 相反，它通过移动终结点来“规范化”文本范围，使范围完全包含指定的文本单位。 如果范围小于指定的单位，则扩大;如果范围长于指定单位，则缩短范围。 下图显示了 ExpandToEnclosingUnit 如何通过移动范围的终结点来规范化文本范围。

如果文本范围从文本单元的开头开始，到下一个文本单元边界的开头或之前结束，则结束终结点将移动到下一个文本单元边界 (上图) 图中的 1 和 2。

如果文本范围从文本单元的开头开始，到下一个单元边界结束或之后结束，则结束终结点将保留或向后移动到下一个单位边界后，起始端点 (上图) 中所示的 3 和 4。 如果起始终结点和结束终结点之间有多个文本单元边界，则结束终结点将向后移动到起始终结点之后的下一个单元边界，从而产生长度为一个文本单位的文本范围。

如果文本范围从文本单元的中间开始，则起始终结点向后移动到文本单元的开头，并根据需要向前或向后移动到下一个单位边界，起始端点 (上图) 中看到 5 到 8。

调用 IUIAutomationTextRange：：Move 方法时，提供程序按指定的文本单位规范化文本范围。 然后，提供程序按指定的文本单位数向后或向前移动范围。 移动范围时，提供程序将忽略文本中任何嵌入对象的边界。 (但是，单元边界本身可能会受到嵌入对象) 的存在的影响。 下图演示 了 Move 方法如何跨嵌入的对象和文本单元边界逐个移动文本范围。

IUIAutomationTextRange：：MoveEndpointByUnit 方法按指定的文本单位向前或向后移动其中一个终结点。 下图显示了终结点如何向前移动。

IUIAutomationTextRange：：MoveEndpointByRange 方法使客户端应用程序能够将文本范围的一个终结点设置为与第二个文本范围的指定终结点相同的位置。

将文本范围滚动到视图中

IUIAutomationTextRange：：ScrollIntoView 方法滚动文本范围，以便文本在基于文本的控件的视区中可见。 调用 ScrollIntoView 时，客户端可以指定文本应与视区顶部还是底部对齐。

检索文本范围的封闭元素

客户端应用程序可以使用 IUIAutomationTextRange：：GetEnclosingElement 方法检索包含文本范围的最内层元素的 IUIAutomation 接口指针。 封闭元素通常是提供文本范围的文本提供程序。 但是，如果文本提供程序支持子元素（如表或超链接），则封闭元素可能是文本提供程序的后代。

比较和克隆文本范围

IUIAutomationTextRange 接口包括两种用于比较文本范围的方法。 IUIAutomationTextRange：：Compare 方法比较两个文本范围的起始终结点和结束终结点，如果两个终结点相同，则返回 TRUE。 IUIAutomationTextRange：：CompareEndpoints 方法比较两个范围的开始或结束终结点。 如果终结点相同，则返回值为零，或者指示两个终结点的相对位置的正值或负值。

客户端应用程序可以使用 IUIAutomationTextRange：：Clone 方法创建文本范围的精确副本。 新文本范围可以独立于原始文本范围进行操作。

检索批注

如果基于文本的控件支持批注，则文本范围可以包含批注。 有许多不同类型的批注。 UIAutomationClient.h 头文件定义一组命名常量值，用于标识UI 自动化支持的批注类型。 有关详细信息，请参阅 批注类型标识符。

某些类型的批注由支持 Annotation 控件模式的自动化元素表示 (IUIAutomationAnnotationPattern 接口) 。 其他类型的批注通过 TextRange 控件模式公开。 例如，提供程序可以通过让 IUIAutomationTextRange：：GetAttributeValue 方法返回 annotationTypes 文本属性 AnnotationType_SpellingError和 AnnotationObjects 文本属性的 null 值来公开简单的拼写错误指示器。

从文本范围检索批注类型

可以使用 IUIAutomationTextRange：：GetAttributeValue 方法检索文本区域中存在的批注类型的列表。 调用 方法时，请指定文本属性 ID UIA_AnnotationTypesAttributeId ，并指定指向 VARIANT 类型的参数的指针。 当方法返回时， VARIANT 参数包含批注类型标识符的列表，文本范围中每种类型的批注都有一个。 有关详细信息，请参阅 批注类型标识符。

从文本范围检索所有批注

若要从文本范围检索批注，请调用 IUIAutomationTextRange：：GetAttributeValue 方法，将文本属性 ID 指定 为 UIA_AnnotationObjectsAttributeId ，并指定指向 VARIANT 类型的参数的指针。 当方法返回时， VARIANT 参数包含一个 IUIAutomationElementArray 接口，该接口表示一组自动化元素，文本范围中的每个批注对应一个。 IUIAutomationElementArray：：Length 属性指示数组中的元素数，IUIAutomationElementArray：：GetElement 方法检索特定元素的 IUIAutomationElement 接口。

检索有关特定批注的信息

若要检索有关特定批注的信息，请首先检索注释元素的 IUIAutomationElement 接口，如上一节中所述。 接下来，通过调用 IUIAutomationElement：：GetCurrentPatternAs 方法检索批注的 IUIAutomationAnnotationPattern 接口，该方法的控件模式 ID 为 UIA_AnnotationPatternId，接口标识符为 IID_IUIAutomationAnnotationPattern，以及接收批注的 IUIAutomationAnnotation 指针的变量的地址。 查询 IUIAutomationAnnotation 接口的属性，以检索批注类型名称和类型 ID、批注作者的名称、批注的日期和时间，以及要批注的元素的 IUIAutomationElement 接口。

检索批注目标文本

通常，批注适用于文本范围中的某些文本子集。 检索批注的 IUIAutomationElement 接口后，可以将该接口传递给 IUIAutomationTextRange2：：RangeFromAnnotation 方法，以检索包含作为批注目标的文本的文本范围。

检索视觉样式

提供程序实现 Styles 控件模式来描述具有特定样式、填充颜色、填充图案或形状的 UI 元素。 这在描述文档中经常具有此类样式的元素时特别有用。 此类样式通常包含对残障客户有用的信息;例如，样式可以将某个字符串描述为文档的标题，或将某个流程图对象描述为菱形或圆形。

可以使用 IUIAutomationTextRange：：GetAttributeValue 方法检索文本范围中使用的视觉样式的名称和标识符。 使用 UIA_StyleNameAttributeId text 属性检索样式名称， 使用 UIA_StyleIdAttributeId 检索样式标识符。

支持视觉样式的基于文本的控件可以实现 Styles 控件模式，使客户端能够访问有关控件使用的视觉样式的信息。 客户端通过 IUIAutomationStylesPattern 接口访问 Styles 控件模式。 可以通过调用 IUIAutomationElement：：GetCurrentPattern 或 GetCurrentPatternAs 方法检索此接口，并将 UIA_StylesPatternId 指定为控件模式标识符。

IUIAutomationStylesPattern 接口包括提供有关视觉样式的以下信息的属性和方法：

• 视觉样式的名称，例如“Normal”或“Heading 1”。
• 视觉样式的标识符。 有关详细信息，请参阅 样式标识符。
• 用于填充基于文本的控件的颜色。
• 用于填充基于文本的控件的图案的颜色。
• 基于文本的控件的形状。
• 扩展属性;即特定于控件的样式名称和值的列表。

从文本范围调用上下文菜单

从 Windows 8.1 开始，文本范围可能支持 IUIAutomationTextRange2 接口。 此接口支持 ShowContextMenu 方法。 可以调用此方法来调用与文本范围关联的任何上下文菜单。 此方案是自动更正文本范围或 IME 候选项选择。 在这些情况下，将显示支持用户交互的上下文菜单。

相关主题

Text 和 TextRange 控件模式

对文本内容的UI 自动化支持

使用基于文本的控件