注释
本文档适用于想要使用 System.Windows.Automation 命名空间中定义的托管 UI 自动化类的 .NET Framework 开发人员。 有关 UI 自动化的最新信息，请参阅 Windows 自动化 API：UI 自动化。
本概述介绍如何Microsoft UI 自动化在文本文档或容器中公开嵌入的对象或子元素。
在 UI 自动化中，嵌入对象是具有非文本边界的任何元素;例如，图像、超链接、表格或文档类型，例如Microsoft Excel 电子表格或Microsoft Windows Media 文件。 这不同于标准定义，即在一个应用程序中创建元素，并在另一个应用程序中嵌入或链接元素。 是否可以在对象的原始应用程序中编辑对象与 UI 自动化的上下文无关。
嵌入的对象和 UI 自动化树
嵌入对象被视为 UI 自动化树控件视图中的各个元素。 由于它们都是作为文本容器的子级公开的，因此可以通过与 UI 自动化中的其他控件相同的模型进行访问。
包含表、图像和超链接嵌入对象的文本容器示例
上述文本容器的一部分的内容视图示例
使用 TextPattern 和 TextPatternRange 公开嵌入式对象
结合使用时，TextPattern 控制模式类和 TextPatternRange 类公开了方法和属性，以帮助导航和查询嵌入对象。
文本容器的文本内容（或内部文本）和嵌入对象（如超链接或表格单元格）公开为控件视图和 UI 自动化树的内容视图中的单个连续文本流;将忽略对象边界。 如果 UI 自动化客户端正在检索文本，以便以某种方式进行背诵、解释或分析，则应检查文本范围是否存在特殊情况，例如包含文本内容或其他嵌入对象的表。 这可以通过调用 GetChildren 以获取每个嵌入对象的一个 AutomationElement ，然后调用 RangeFromChild 以获取每个元素的文本范围来实现。 此作以递归方式完成，直到检索到所有文本内容。
包含嵌入对象及其范围的文本流示例
当需要遍历文本范围的内容时，幕后涉及一系列步骤，以成功执行Move方法。
对文本范围进行了规范化。也就是说，已在 Start 终结点将文本范围折叠为退化范围，这使得 End 终结点成为多余。 在文本范围跨越 TextUnit 边界的情况下，需要执行此步骤来消除歧义：例如，
{The URL https://www.microsoft.com is embedded in text其中“{”和“}”是文本范围终结点。生成的范围在 DocumentRange 中向后移动到所请求的 TextUnit 边界的开头。
在DocumentRange中，范围按请求的TextUnit边界数量向前或向后移动。
如何针对 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 - 部分跨越嵌入文本超链接的文本范围
URL https://{[www]} 嵌入在文本中。
| 调用的方法 | 结果 |
|---|---|
| GetText | 返回字符串“www”。 |
| GetEnclosingElement | 返回包含文本范围的最内层AutomationElement控件；在本例中，为超链接控件。 |
| GetChildren | 返回值 null ，因为文本范围不会跨越整个 URL 字符串。 |
示例 3 - 部分跨越文本容器内容的文本范围。 文本容器具有不属于文本范围的嵌入文本超链接。
{The URL} [https://www.microsoft.com](https://www.microsoft.com) is embedded in text.
| 调用的方法 | 结果 |
|---|---|
| GetText | 返回字符串“URL”。 |
| GetEnclosingElement | 返回最内层的 AutomationElement ，它包含文本范围；在这种情况下，最内层的 AutomationElement 表示文本提供程序本身。 |
| Move 的参数为 (TextUnit.Word, 1)。 | 将文本范围范围移动到“http”，因为超链接的文本由单个单词组成。 在这种情况下，超链接不被视为单个对象。 URL {[http]} 嵌入在文本中。 |
图片
示例 1 - 包含嵌入图像的文本范围
{图像 
被嵌入文本中}。
| 调用的方法 | 结果 |
|---|---|
| GetText | 返回字符串“The is embedded in text”。 与图像关联的任何 ALT 文本都不应包含在文本流中。 |
| GetEnclosingElement | 返回最内层的 AutomationElement ，它包含文本范围；在这种情况下，最内层的 AutomationElement 表示文本提供程序本身。 |
| GetChildren | 返回一个表示图像控件的 AutomationElement。 |
| RangeFromChild 其中 AutomationElement ，上一 GetChildren 方法返回的对象。 | 返回表示“”的退化范围。 |
示例 2 - 部分跨越文本容器内容的文本范围。 文本容器具有不属于文本范围的嵌入图像。
{图像} 嵌入文本中。
| 调用的方法 | 结果 |
|---|---|
| GetText | 返回字符串“图像”。 |
| GetEnclosingElement | 返回最内层的 AutomationElement ，它包含文本范围；在这种情况下，最内层的 AutomationElement 表示文本提供程序本身。 |
| Move 的参数为 (TextUnit.Word, 1)。 | 将文本范围跨度移到“is ”。 由于仅基于文本的嵌入对象被视为文本流的一部分，因此此示例中的图像不会影响 Move 或其返回值（在本例中为 1）。 |
表
用于示例的表
| 带图像的单元格 | 带文本的单元格 |
|---|---|
|
|
X |
|
Y |
Z 的图像 |
Z |
示例 1 - 从单元格的内容获取文本容器。
| 调用方法 | 结果 |
|---|---|
| 具有参数 (0,0) 的 GetItem | 返回 AutomationElement 表示表单元格的内容;在本例中，元素是文本控件。 |
RangeFromChild 其中 AutomationElement ，上一 GetItem 方法返回的对象。 |
返回涵盖图像 的范围。 |
GetEnclosingElement 上一个RangeFromChild方法所返回的对象。 |
返回 AutomationElement 表示表单元格;在本例中，元素是支持 TableItemPattern 的文本控件。 |
GetEnclosingElement 上一个GetEnclosingElement方法所返回的对象。 |
返回表示表格的 AutomationElement 。 |
GetEnclosingElement 上一个GetEnclosingElement方法所返回的对象。 |
返回表示文本提供程序本身的 AutomationElement 。 |
示例 2 - 获取单元格的文本内容。
| 调用方法 | 结果 |
|---|---|
| GetItem 参数为 （1,1）。 | 返回 AutomationElement 表示表单元格的内容;在本例中，元素是文本控件。 |
RangeFromChild 其中 AutomationElement ，上一 GetItem 方法返回的对象。 |
返回“Y”。 |