TextPattern 和嵌入式对象概述

2008-09-04

更新：2007 年 11 月

本概述介绍 Microsoft UI 自动化如何在文本文档或容器内公开嵌入的对象或子元素。

在 UI 自动化中，嵌入对象是具有非文本边界的任何元素；例如图像、超链接、表或诸如 Microsoft Excel 电子表格或 Microsoft Windows Media 文件等文档类型。这与标准定义不同，在标准定义中，元素是在一个应用程序中创建的，并嵌入或链接到另一个应用程序内。是否能够在对象的原始应用程序内编辑对象与 UI 自动化的上下文无关。

本主题包括下列各节。

嵌入对象和 UI 自动化树
使用 TextPattern 和 TextPatternRange 公开嵌入对象
常见的情况
相关主题

嵌入对象和 UI 自动化树

嵌入对象被视为 UI 自动化树的控件视图内的单独元素。这些对象作为文本容器的子项公开，以使其可以通过与 UI 自动化中其他控件相同的模型来访问。

包含表、图像和超链接嵌入对象的文本容器的示例

文本容器中有图像的嵌入式表

前面文本容器的一部分的内容视图的示例

前面示例的内容视图

使用 TextPattern 和 TextPatternRange 公开嵌入对象

在结合使用时，TextPattern控件模式类和 TextPatternRange 类将公开便于嵌入对象的导航和查询的方法和属性。

文本容器和嵌入对象（如超链接或表格单元格）的文本内容（即内部文本）在 UI 自动化树的控件视图和内容视图中都以一个连续文本流的形式公开；将忽略对象边界。如果 UI 自动化客户端出于叙述、解释或分析目的以某种方式检索文本，则应检查文本范围中是否有特殊情况，比如表中含有文本内容或其他嵌入对象。可通过以下方式实现此目的：调用 GetChildren 获取每个嵌入对象的 AutomationElement，然后调用 RangeFromChild 获取每个元素的文本范围。此操作将以递归方式进行，直至检索了所有文本内容为止。

包含嵌入对象及其范围跨度的文本流的示例

嵌入式对象所跨的文本范围。

如果有必要遍历文本范围的内容，则会在后台执行一系列步骤以使 Move 方法成功执行。

会对文本范围进行规范化；也就是说，文本范围会被收缩到 Start 端点处的一个退化范围，从而使 End 端点失去意义。在某些情况下，文本范围会跨越 TextUnit 边界（例如，“{The U}RL https://www.microsoft.com is embedded in text”，此处的“{”和“}”表示文本范围的端点），为了消除这种情况带来的不确定性，必须执行此步骤。
最终的范围在 DocumentRange 中向后移动到所请求 TextUnit 边界的开始处。
范围在 DocumentRange 中向前或向后移动所请求的若干个 TextUnit 边界。
然后，范围从退化范围状态进行扩展，方法是将 End 端点移动一个请求的 TextUnit 边界。

文本范围针对 Move() 和 ExpandToEnclosingUnit() 进行调整的示例

通过 Move 和 ExpandToEnclosingUnit 进行的范围调整

常见的情况

以下各节介绍了涉及嵌入对象的大多数常见情况的示例。

所显示示例的图例：

{ = Start

} = End

超链接

示例 1 — 包含嵌入文本超链接的文本范围

{The URL https://www.microsoft.com is embedded in text}。

调用的方法	结果
GetText	返回字符串“The URL https://www.microsoft.com is embedded in text”。
GetEnclosingElement	返回封闭文本范围的最内层 AutomationElement；本例中为表示文本提供程序本身的 AutomationElement。
GetChildren	返回表示超链接控件的 AutomationElement。
RangeFromChild，其中 AutomationElement 是前面的 GetChildren 方法返回的对象。	返回表示“https://www.microsoft.com”的范围。

示例 2 — 部分跨越嵌入文本超链接的文本范围

The URL http://{www}.microsoft.com is embedded in text.

调用的方法	结果
GetText	返回字符串“www”。
GetEnclosingElement	返回封闭文本范围的最内层 AutomationElement；本例中为超链接控件。
GetChildren	返回 null，因为文本范围未跨越整个 URL 字符串。

示例 3 — 部分跨越文本容器内容的文本范围。文本容器包含不属于文本范围的嵌入文本超链接。

{The URL} https://www.microsoft.com is embedded in text.

调用的方法	结果
GetText	返回字符串“The URL”。
GetEnclosingElement	返回封闭文本范围的最内层 AutomationElement；本例中为表示文本提供程序本身的 AutomationElement。
参数为 (TextUnit.Word, 1) 的 Move。	将文本范围跨度移到“http”，因为超链接的文本由单独的词组成。本例中未将超链接视为单一对象。 The URL {http}://www.microsoft.com is embedded in text.

GetText

返回字符串“The URL”。

GetEnclosingElement

返回封闭文本范围的最内层 AutomationElement；本例中为表示文本提供程序本身的 AutomationElement。

参数为 (TextUnit.Word, 1) 的 Move。

将文本范围跨度移到“http”，因为超链接的文本由单独的词组成。本例中未将超链接视为单一对象。

The URL {http}://www.microsoft.com is embedded in text.

图像

示例 1 — 包含嵌入图像的文本范围

{The image 嵌入式图像示例 is embedded in text}.

调用的方法	结果
GetText	返回字符串“The is embedded in text”。无法指望与图像关联的任何 ALT 文本会包括在文本流中。
GetEnclosingElement	返回封闭文本范围的最内层 AutomationElement；本例中为表示文本提供程序本身的 AutomationElement。
GetChildren	返回表示图像控件的 AutomationElement。
RangeFromChild，其中 AutomationElement 是前面的 GetChildren 方法返回的对象。	返回表示“”的退化范围。

示例 2 — 部分跨越文本容器内容的文本范围。文本容器包含不属于文本范围的嵌入图像。

{The image} 嵌入式图像示例 is embedded in text.

调用的方法	结果
GetText	返回字符串“The image”。
GetEnclosingElement	返回封闭文本范围的最内层 AutomationElement；本例中为表示文本提供程序本身的 AutomationElement。
参数为 (TextUnit.Word, 1) 的 Move。	将文本范围跨度移到“is ”。由于仅将基于文本的嵌入对象视为文本流的一部分，因此本例中的图像不会影响 Move 或它的返回值（本例中为 1）。

表

用于示例的表

包含图像的单元格	包含文本的单元格
	X
	Y
Z 的图像	Z

嵌入式图像示例

嵌入式图像示例 2

嵌入式图像示例 3

Z 的图像

示例 1 — 从单元格的内容中获取文本容器。

调用的方法	结果
参数为 (0,0) 的 GetItem	返回表示表单元格内容的 AutomationElement；在本例中，元素是文本控件。
RangeFromChild，其中 AutomationElement 是前面的 GetItem 方法返回的对象。	返回跨越图像的范围。
前面的 RangeFromChild 方法所返回对象的 GetEnclosingElement。	返回表示表单元格的 AutomationElement；在本例中，元素是支持 TableItemPattern 的文本控件。
前面的 GetEnclosingElement 方法所返回对象的 GetEnclosingElement。	返回表示表的 AutomationElement。
前面的 GetEnclosingElement 方法所返回对象的 GetEnclosingElement。	返回表示文本提供程序本身的 AutomationElement。

示例 2 — 获取单元格的文本内容。

调用的方法	结果
参数为 (1,1) 的 GetItem。	返回表示表单元格内容的 AutomationElement；在本例中，元素是文本控件。
RangeFromChild，其中 AutomationElement 是前面的 GetItem 方法返回的对象。	返回“Y”。