UI 自动化如何公开嵌入对象

项目
06/13/2023

本主题介绍 Microsoft UI 自动化如何使用 Text 和 TextRange 控件模式来公开嵌入对象 (文本文档或容器中) 子/子元素。

对于UI 自动化，嵌入对象是具有非文本边界（如图像、超链接、表格或文档类型）的任何元素， (Microsoft Excel 电子表格、Microsoft Windows Media 文件等) 。

注意

这不同于组件对象模型 (COM) OLE 定义 (请参阅嵌入对象) ，其中元素在一个应用程序中创建，并在另一个应用程序中嵌入或链接。对象是否可以在其原始应用程序中编辑，与UI 自动化上下文无关。

嵌入对象和 UI 自动化树

嵌入对象被视为UI 自动化树的控件视图中的单个元素。它们作为文本容器的子级公开，以便可以通过与 UI 自动化中的其他控件相同的对象模型访问它们。

下表列出了容器和非容器元素的示例。

容器元素

非容器元素

日历
Combobox
DataGrid
文档
编辑
Group
标头
HeaderItem
列表
菜单

MenuBar
窗格
SplitButton
Tab
表
工具栏
树
TreeItem
窗口

链接
CheckBoxes
Button

下图显示了一个文本容器， (带有嵌入表和图像的文档) 。

显示具有嵌入表格和图像的文档的插图

下图显示了上一文档的UI 自动化内容视图。

包含嵌入对象的文档的 ui 自动化内容视图的示意图

“兼容”和“不兼容”嵌入对象

某些UI 自动化提供程序为其包含的每个 TextPattern 对象使用相同的文本存储。由与其容器相同的文本存储支持的对象称为“兼容”嵌入对象。这些对象本身可以是 TextPattern 对象，在本例中，其文本范围与从其容器获取的文本范围相当。这使提供程序能够公开有关单个 TextPattern 对象的客户端信息，就好像它们是一个大型文本提供程序一样。

但是，提供程序可以对嵌入在 TextPattern 容器中的不同 TextPattern 对象使用不同的文本存储。不受容器的文本存储支持的对象称为“不兼容”嵌入对象。这些类型的嵌入对象可能是基于 TextPattern 的对象，也可能不是。

下表列出了兼容和不兼容嵌入式对象的一些示例。

对象	兼容的嵌入对象	不兼容的嵌入对象
非 TextPattern 嵌入对象	Microsoft Edge 中的按钮 Microsoft Edge 中的数据表	Microsoft XAML 框架中 RichTextBlock 中的按钮 Microsoft Edge 中带有替换文字的图像 Microsoft XAML 框架中 RichTextBlock 中的 ListView 和 ListItems
TextPattern 嵌入对象	Microsoft Edge 中“text”类型的输入控件 Word文档中的表格	Microsoft Word文档中的 TextBox 元素

公开嵌入对象

Text 和 TextRange 控件模式公开有助于导航和查询嵌入对象的属性和方法。

文本容器和嵌入对象（如超链接或表格单元格）的文本内容（或内部文本）在 UI 自动化树的控件视图和内容视图中作为单个连续文本流公开，对象边界被忽略。如果UI 自动化客户端正在以某种方式检索要背诵、解释或分析的文本，则应检查文本范围是否存在特殊情况，例如包含文本内容或其他嵌入对象的表。调用 IUIAutomationTextRange：：GetChildren 以获取每个嵌入对象的 IUIAutomationElement 接口，然后调用 IUIAutomationTextPattern：：RangeFromChild 以获取每个元素的文本范围。以递归方式完成操作，直到检索到所有文本内容。

注意

退化 (或折叠) 范围是起始终结点和结束终结点相同的地方。退化范围通常用于通过 ITextProvider GetSelection 和 GetCaretRange 方法指示文本光标位置。

下图显示了包含嵌入对象及其范围范围的文本流。

显示包含嵌入对象的文本流及其范围范围的示意图

嵌入的对象和 TextUnit

ITextProvider 对象可由指定的 TextUnit 遍历。包含嵌入对象的提供程序的遍历方式大致相同，但嵌入对象确实会影响遍历。下面是需要注意的一些事项：

任何不兼容的嵌入对象都由容器元素的 TextPattern 的文本存储中的替换字符 U+FFFC 表示。它还被视为字符单位和单词单位。
兼容的嵌入对象可能包含多个字符和单词。
封闭元素是跨越整个文本范围的最底部元素。
范围的子元素也是部分或完全封闭在范围内的容器元素的子元素。
理想情况下 (尤其是在容器元素（如 Table) 字边界不会超出对象边界的情况下）。在下面的示例中，单词单元“Bar”不包含标记之外 </td> 的任何文本位置， (<br \> 不是单词“Bar”) 的一部分。

<table style="width:100%">
  <tr>
    <th>Name</th>
    <th>Notes</th>
  </tr>
  <tr>
    <td>Eve Jackson</td>
    <td>Foo Bar</td>
  </tr>
</table>
<br/>

通常， <br \> 被视为单个单词，因此它不会超出线条边界。
上一个规则的例外情况是，Word文本单元在自身中包含完整的对象。例如， <p>Hello <a href="#">link</a> here.</p>包含内联容器的单词“Hello”、“link”和“here”。其中，“link”有一个 TextPattern 对象作为封闭元素，一个链接对象作为其子元素。
对于字符单位，对象是封闭元素 (这样的文本单位不应有子) 。
注释对象不应表示为嵌入对象。例如，在共同创作的文档中是否存在其他作者说明符。
嵌入对象占用至少一个光标位置，批注只是元数据。
每个对象边界 (开始和结束) 由 TextPattern 文档区域中的格式分隔符表示。
对于 HTML，每个 html 标记不一定会导致UI 自动化对象。例如，强调标记内的内容不需要表示为元素，而是表示UIA_IsItalicAttributeId返回 TRUE 的文本流。
启动终结点是非独占终结点，并且是首选终结点，而结束终结点是独占的。当范围退化并且开始终结点和结束终结点属于该范围的位置相同时，这非常有用。

比较嵌入对象

在类似的子关系中并共享同一后备文本存储的嵌套 TextPattern 对象称为可比较对象。在这种情况下，可以使用 ITextRangeProvider：：Compare 和 ITextRangeProvider：：CompareEndpoints 比较来自任一 TextPattern 对象的范围。两者都生成一个有效的数值，用于指定它们的相对位置。

如果 TextPattern 对象在 TextPattern (ITextProvider：：RangeFromChild) 且文本范围背后的内容不为空且不是替换字符，则嵌入在 TextPattern 对象中的非 TextPattern 对象与 TextPattern 相当。

嵌入的 TextPattern 对象和文档 TextUnit

对于嵌入的 TextPattern 对象， Document 单元仅识别该元素中包含的内容。

Word TextPattern 元素层次结构

document 元素实现 TextPattern，Document 返回整个Word文档范围。
文档的各个页面实现 TextPattern ，文档返回这些页面的内容 (即使页面与整个文档 TextPattern) 共享相同的文本存储。

Edge 中的网页和文本输入控件

main网页 Pane 元素实现 TextPattern 并公开整个网页内容。
单个文本输入控件支持 TextPattern，其中文档范围表示每个输入字段中包含的文本 (即使它们与整个网页) 共享相同的文本存储。

常见方案

本部分提供涉及嵌入对象的常见方案示例：超链接、图像和表。在以下示例中，左大括号 ({) 表示文本范围的开始终结点，右大括号 (}) 表示 End 终结点。

HyperLink 示例 1：包含嵌入文本超链接的文本区域

以下文本范围包含嵌入的文本超链接。

{URL https://www.microsoft.com 嵌入在文本中}。

调用 IUIAutomationTextRange：：GetText、 GetEnclosingElement、 GetChildren 和 IUIAutomationTextPattern：：RangeFromChild 方法会导致下表中所述的行为。

调用方法	结果
IUIAutomationTextRange：：GetText	返回字符串“URL https://www.microsoft.com 嵌入在文本中”。
IUIAutomationTextRange：：GetEnclosingElement	返回包含文本范围的最内部UI 自动化元素，在本例中为表示文本提供程序本身的自动化元素。
IUIAutomationTextRange：：GetChildren	返回表示超链接控件的UI 自动化元素。
IUIAutomationTextPattern：：RangeFromChild，其中 UI 自动化元素由以前的 IUIAutomationTextRange：：GetChildren 方法返回。	返回表示“;”https://www.microsoft.com"的区域。

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

以下文本范围部分跨越嵌入文本超链接。

URL https://{www} 嵌入在文本中。

调用 IUIAutomationTextRange：：GetText、 GetEnclosingElement 和 GetChildren 方法会导致下表中所述的行为。

调用方法	结果
IUIAutomationTextRange：：GetText	返回字符串“www”。
IUIAutomationTextRange：：GetEnclosingElement	返回包含文本范围的最内部UI 自动化元素;在本例中为超链接控件。
IUIAutomationTextRange：：GetChildren	返回 NULL ，因为文本范围不跨整个 URL 字符串。

HyperLink 示例 3：部分跨越文本容器内容的文本范围

以下文本范围部分跨越文本容器的内容。文本容器包含不属于文本范围一部分的嵌入文本超链接。

{URL} https://www.microsoft.com 嵌入在文本中。

调用 IUIAutomationTextRange：：GetText、 GetEnclosingElement 和 Move 方法会导致下表中所述的行为。

调用方法	结果
IUIAutomationTextRange：：GetText	返回字符串“The URL”。
IUIAutomationTextRange：：GetEnclosingElement	返回包含文本范围的最内部UI 自动化元素，在本例中为表示文本提供程序本身的元素。
IUIAutomationTextRange：：Move	将文本范围移动到“https://”，因为超链接的文本由单个单词组成。在本例中，不将超链接视为单个对象。 The URL {http} is embedded in text。

图像示例 1：包含嵌入图像的文本区域

以下文本范围包含一个航天飞机的嵌入图像。

{ 航天飞机的图像插图嵌入在文本中}。

调用 IUIAutomationTextRange：：GetText、 GetEnclosingElement、 GetChildren 和 IUIAutomationTextPattern：：RangeFromChild 方法会导致下表中所述的行为。

调用方法	结果
IUIAutomationTextRange：：GetText	返回字符串“图像嵌入在文本中”。与图像关联的任何 ALT 文本不包括在文本流中。
IUIAutomationTextRange：：GetEnclosingElement	返回包含文本范围的最内部UI 自动化元素，在本例中为表示文本提供程序本身的元素。
IUIAutomationTextRange：：GetChildren	返回表示图像控件的UI 自动化元素。
IUIAutomationTextPattern：：RangeFromChild，其中UI 自动化元素由以前的 IUIAutomationTextRange：：GetChildren 方法返回。	返回退化范围。

图像示例 2：部分跨越文本容器内容的文本范围

以下文本范围部分跨越文本容器的内容。文本容器包含不属于文本范围的一部分的嵌入图像。

{The image}文本中嵌入了穿梭的插图。

调用 IUIAutomationTextRange：：GetText、 GetEnclosingElement 和 Move 方法会导致下表中所述的行为。

调用方法	结果
IUIAutomationTextRange：：GetText	返回字符串“The image”。
IUIAutomationTextRange：：GetEnclosingElement	返回包含文本范围的最内部UI 自动化元素，在本例中为表示文本提供程序本身的元素。
IUIAutomationTextRange：：Move ，参数为 (TextUnit_Word，2) 。	将文本范围跨度移到“is ”。由于仅将基于文本的嵌入对象视为文本流的一部分，因此此示例中的图像不会影响 IUIAutomationTextRange：：Move 或其返回值，在本例中为 2。

表

表示例 1：从单元格的内容获取文本容器

下表从单元格的内容获取文本容器。

带图像的单元格	带文本的单元格
	X
	Y
	Z

调用 IUIAutomationGridPattern：：GetItem、 IUIAutomationTextPattern：：RangeFromChild 和 IUIAutomationTextRange：：GetEnclosingElement 方法会导致下表中所述的行为。

调用方法	结果
参数 (0、0) 的 IUIAutomationGridPattern：：GetItem。	返回表示表格单元格内容的UI 自动化元素，在本例中，该元素为文本控件。
iuiautomationtextpattern：：rangefromchild	返回的范围。
上一个 IUIAutomationTextPattern：：RangeFromChild 方法返回的对象 GetEnclosingElement。	返回表示表格单元格的UI 自动化元素。在这种情况下，元素是支持 TableItem 控件模式的文本控件。
上一个 GetEnclosingElement 方法返回的对象 IUIAutomationTextRange：：GetEnclosingElement。	返回表示表的UI 自动化元素。
上一个 GetEnclosingElement 方法返回的对象 IUIAutomationTextRange：：GetEnclosingElement。	返回表示文本提供程序本身UI 自动化元素。

表示例 2：获取单元格的文本内容

上例中的表获取单元格的文本内容。

调用 IUIAutomationGridPattern：：GetItem 和 IUIAutomationTextPattern：：RangeFromChild 方法会导致下表中所述的行为。

调用方法	结果
参数 (1，1) 的 IUIAutomationGridPattern：：GetItem。	返回表示表格单元格内容的UI 自动化元素。在本例中，元素是一个文本控件。
IUIAutomationTextPattern：：RangeFromChild，其中UI 自动化元素是由以前的 IUIAutomationGridPattern：：GetItem 方法返回的对象。	返回“Y”。

按 TextUnit_Line在文档中移动时，如果文本区域进入嵌入表格，单元格中的每一行文本都应被视为一行。

Share via

UI 自动化如何公开嵌入对象