.gif "注意") 注意 |
|---|
本文档的目标读者是欲使用 System.Windows.Automation 命名空间中定义的托管 UI Automation类的 .NET Framework 开发人员。有关 UI Automation的最新信息，请参见 Windows Automation API: UI Automation（Windows 自动化 API：UI 自动化）。 |
本概述介绍 Microsoft UI Automation如何在文本文档或容器内公开嵌入的对象或子元素。
在 UI Automation中，嵌入对象是具有非文本边界的任何元素；例如图像、超链接、表或诸如 Microsoft Excel 电子表格或 Microsoft Windows Media 文件等文档类型。 这与标准定义不同，在标准定义中，元素是在一个应用程序中创建的，并嵌入或链接到另一个应用程序内。 是否能够在对象的原始应用程序内编辑对象与 UI Automation的上下文无关。
本主题包括下列各节。
- 嵌入对象和 UI 自动化树
- 使用 TextPattern 和 TextPatternRange 公开嵌入对象
- 常见的情况
- 相关主题
嵌入对象和 UI 自动化树
嵌入对象被视为 UI Automation树的控件视图内的单独元素。 这些对象作为文本容器的子项公开，以使其可以通过与 UI Automation中其他控件相同的模型来访问。
包含表、图像和超链接嵌入对象的文本容器的示例
.png "文本容器中有图像的嵌入式表")
前面文本容器的一部分的内容视图的示例
.png "前面示例的内容视图")
使用 TextPattern 和 TextPatternRange 公开嵌入对象
在结合使用时，TextPattern 控件模式类和 TextPatternRange 类将公开便于嵌入对象的导航和查询的方法和属性。
文本容器和嵌入对象（如超链接或表格单元格）的文本内容（或内部文本）在 UI Automation树的控件视图和内容视图中都以连续的单一文本流的形式公开；将忽略对象边界。如果 UI 自动化客户端出于叙述、解释或分析的目的以某种方式检索文本，则应检查文本范围中是否有特殊情况，比如包含文本内容或其他嵌入对象的表格。 可通过以下方式实现此目的：调用 GetChildren 获取每个嵌入对象的 AutomationElement，然后调用 RangeFromChild 获取每个元素的文本范围。 此操作将以递归方式进行，直至检索了所有文本内容为止。
包含嵌入对象及其范围跨度的文本流的示例
.png "嵌入式对象所跨的文本范围。")
如果有必要遍历文本范围的内容，则会在后台执行一系列步骤以使 Move 方法成功执行。
将对文本范围进行规范化；也就是说，文本范围会被收缩到位于 Start 端点处的一个退化范围，从而使 End 端点失去意义。 在某些情况下，文本范围会跨越 TextUnit 边界（例如，“{The U}RL https://www.microsoft.com is embedded in text”，此处的“{”和“}”表示文本范围的端点），为了消除这种情况带来的不确定性，必须执行此步骤。
最终的范围在 DocumentRange 中向后移动到所请求 TextUnit 边界的开始处。
范围在 DocumentRange 中向前或向后移动所请求的若干个 TextUnit 边界。
文本范围针对 Move() 和 ExpandToEnclosingUnit() 进行调整的示例
.png "通过 Move 和 ExpandToEnclosingUnit 进行的范围调整")
常见的情况
以下各节介绍了涉及嵌入对象的大多数常见情况的示例。
所显示示例的图例：
{ = Start
} = End
Hyperlink
示例 1 — 包含嵌入文本超链接的文本范围
{The URL https://www.microsoft.com is embedded in text}。
调用的方法 |
结果 |
|---|---|
返回字符串“The URL https://www.microsoft.com is embedded in text”。 |
|
返回封闭文本范围的最内层 AutomationElement；本例中为表示文本提供程序本身的 AutomationElement。 |
|
返回表示超链接控件的 AutomationElement。 |
|
RangeFromChild，其中 AutomationElement 是前面的 GetChildren 方法返回的对象。 |
返回表示“https://www.microsoft.com”的范围。 |
示例 2 — 部分跨越嵌入文本超链接的文本范围
URL http://{www} 嵌入在文本中。
调用的方法 |
结果 |
|---|---|
返回字符串“www”。 |
|
返回封闭文本范围的最内层 AutomationElement；本例中为超链接控件。 |
|
返回 null，因为文本范围未跨越整个 URL 字符串。 |
示例 3 — 部分跨越文本容器内容的文本范围。 文本容器包含不属于文本范围的嵌入文本超链接。
{The URL} is embedded in text.
调用的方法 |
结果 |
|---|---|
返回字符串“The URL”。 |
|
返回封闭文本范围的最内层 AutomationElement；本例中为表示文本提供程序本身的 AutomationElement。 |
|
参数为 (TextUnit.Word, 1) 的 Move。 |
将文本范围跨度移到“http”，因为超链接的文本由单独的词组成。 本例中未将超链接视为单一对象。 URL {} 嵌入在文本中。 |
Image
示例 1 — 包含嵌入图像的文本范围
{The image .png "嵌入式图像示例")
is embedded in text}.
调用的方法 |
结果 |
|---|---|
返回字符串“The is embedded in text”。 无法指望与图像关联的任何 ALT 文本会包括在文本流中。 |
|
返回封闭文本范围的最内层 AutomationElement；本例中为表示文本提供程序本身的 AutomationElement。 |
|
返回表示图像控件的 AutomationElement。 |
|
RangeFromChild，其中 AutomationElement 是前面的 GetChildren 方法返回的对象。 |
返回表示“ |
示例 2 — 部分跨越文本容器内容的文本范围。 文本容器包含不属于文本范围的嵌入图像。
{The image} is embedded in text.
调用的方法 |
结果 |
|---|---|
返回字符串“The image”。 |
|
返回封闭文本范围的最内层 AutomationElement；本例中为表示文本提供程序本身的 AutomationElement。 |
|
参数为 (TextUnit.Word, 1) 的 Move。 |
将文本范围跨度移到“is ”。 由于仅将基于文本的嵌入对象视为文本流的一部分，因此本例中的图像不会影响 Move 或它的返回值（本例中为 1）。 |
表
用于示例的表
包含图像的单元格 |
包含文本的单元格 |
|---|---|
|
X |
|
Y |
Z 的图像 |
Z |
.png "嵌入式图像示例 2")
.png "嵌入式图像示例 3")
示例 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”。 |
请参见
任务
TextPattern Search and Selection Sample