使用者介面自動化 如何公開內嵌物件

本主題描述Microsoft 使用者介面自動化如何使用 Text 和 TextRange 控制件模式來公開文字檔或容器中的內嵌物件（子系/子代元素）。

對於 使用者介面自動化，內嵌物件是任何具有非文字界限的專案，例如影像、超連結、表格或檔類型（Microsoft Excel 電子表格、Microsoft Windows Media 檔案等等）。

內嵌物件和 UI 自動化樹狀目錄

內嵌物件會被視為 使用者介面自動化 樹狀結構控件檢視中的個別專案。 它們會公開為文字容器的子系，以便透過與 使用者介面自動化 中其他控件相同的物件模型來存取它們。

下表列出容器和非容器專案的範例。

下圖顯示內嵌數據表和影像的文字容器（檔）。

上一份文件的內容檢視 使用者介面自動化 如下圖所示。

“Compatible” 和 “Non-Compatible” 內嵌物件

某些 使用者介面自動化 提供者會針對所包含的每個 TextPattern 物件使用相同的文字存放區。 與容器相同的文字存放區所支援的物件稱為「相容」內嵌物件。 這些物件本身可以是 TextPattern 物件，在此案例中，其文字範圍相當於從其容器取得的文字範圍。 這可讓提供者公開個別 TextPattern 物件的用戶端資訊，就像是一個大型文字提供者一樣。

不過，提供者可以針對內嵌在 TextPattern 容器內的不同 TextPattern 物件使用不同的文字存放區。 容器文字存放區不支援的對象稱為「不相容」內嵌物件。 這些類型的內嵌物件可能或可能不是以 TextPattern 為基礎的物件。

下表列出一些相容和非相容的內嵌物件範例。

公開內嵌物件

Text 和 TextRange 控制項模式會公開屬性和方法，以利瀏覽和查詢內嵌物件。

在 UI 自動化樹狀結構的控制項檢視和內容檢視 (例如超連結或表格儲存格) 中，文字容器和內嵌物件的文字內容 (或內部文字) 會公開為單一連續的文字資料流； 物件界限會被忽略。 如果 使用者介面自動化 用戶端正在擷取要以某種方式背誦、解譯或分析的文字，則應該檢查文字範圍是否有特殊情況，例如含有文字內容或其他內嵌物件的表格。 呼叫 IUIAutomationTextRange：：GetChildren 以取得每個內嵌物件的 IUIAutomationElement 介面，然後呼叫 IUIAutomationTextPattern：：RangeFromChild 以取得每個元素的文字範圍。 這會以遞迴方式進行，直到擷取所有的文字內容為止。

下圖顯示內嵌物件及其範圍範圍的文字數據流。

內嵌物件和 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」 具有 TextPattern 物件做為封入專案，而 link 物件則為其子系。
• 在 Character 單位的情況下，對像是封入專案（類似這樣的文字單位不應該有子系）。
• 註釋物件不應表示為內嵌物件。 例如，共同撰寫檔中存在其他 Author 規範。
• 內嵌物件至少佔用一個游標位置，註釋只是元數據。
• 每個物件界限（開始和結束）都會以 TextPattern 檔範圍中的格式中斷表示。
• 針對 HTML，每個 html 標記不一定會導致 使用者介面自動化 物件。 例如，強調標記內 的內容不需要表示為元素，而是以文字數據流表示，其中UIA_IsItalicAttributeId會傳回 TRUE。
• 啟動端點是內含的，而且是「結束」端點獨佔時慣用的端點。 當範圍變質，而開始和結束端點屬於該範圍的相同位置時，這非常有用。

比較內嵌物件

處於類似子關聯性的巢狀 TextPattern 物件，並共用相同的備份文字存放區，稱為可比較。 在此情況下，可以使用 ITextRangeProvider：：Compare 和 ITextRangeProvider：：CompareEndpoints 來比較其中一個 TextPattern 物件的範圍。 這兩者都會產生有效的數值，以指定其相對位置。

如果物件在 TextPattern （ITextProvider：：RangeFromChild） 中具有有效範圍，則內嵌在 TextPattern 物件中的非 TextPattern 物件與 TextPattern 物件相當，而且文字範圍後面的內容不是空的，而且不是取代字元。

內嵌的 TextPattern 物件和 Document TextUnit

對於內嵌的 TextPattern 物件， Document 單位只會辨識該元素內包含的內容。

Word TextPattern 元素階層

• 文件元素會實作 TextPattern，而 Document 會傳回整個 Word 檔範圍。
• 檔的個別頁面會實作 TextPattern 和 Document 會傳回這些個別頁面的內容（即使頁面與整個檔 TextPattern 共用相同的文字存放區也一樣）。

Edge 中的網頁和文字輸入控件

• 主要網頁 Pane 元素會實作 TextPattern，並公開整個網頁內容。
• 個別文字輸入控件支援 TextPattern，其中檔範圍代表每個輸入欄位中所包含的文字（即使它們與整個網頁共用相同的文字存放區）。

常見案例

本節提供涉及內嵌對象的常見案例範例：超連結、影像和數據表。 在下列範例中，左大括弧 （{） 代表文字範圍的開始端點，而右大括號 （}） 則代表 End 端點。

HyperLink 範例 1：包含內嵌文字超連結的文字範圍

下列文字範圍包含內嵌的文字超連結。

{URL https://www.microsoft.com 內嵌在文字中}。

呼叫 IUIAutomationTextRange：：GetText、GetEnclosingElement、GetChildren 和 IUIAutomationTextPattern：：RangeFromChild 方法會導致下表所述的行為。

HyperLink 範例 2：部分跨越內嵌文字超連結的文字範圍

下列文字範圍會部分跨越內嵌文字超連結。

URL https://{www} 內嵌在文字中。

呼叫 IUIAutomationTextRange：：GetText、GetEnclosingElement 和 GetChildren 方法會導致下表所述的行為。

HyperLink 範例 3：部分跨越文字容器內容的文字範圍

下列文字範圍會部分跨越文字容器的內容。 此文字容器有不屬於此文字範圍的內嵌文字超連結。

{URL} https://www.microsoft.com 內嵌在文字中。

呼叫 IUIAutomationTextRange：：GetText、GetEnclosingElement 和 Move 方法會導致下表所述的行為。

影像範例 1：包含內嵌影像的文字範圍

下列文字範圍包含航太飛機的內嵌影像。

{影像 內嵌在文字中}。

呼叫 IUIAutomationTextRange：：GetText、GetEnclosingElement、GetChildren 和 IUIAutomationTextPattern：：RangeFromChild 方法會導致下表所述的行為。

影像範例 2：部分跨越文字容器內容的文字範圍

下列文字範圍會部分跨越文字容器的內容。 此文字容器有不屬於此文字範圍的內嵌影像。

{影像} 內嵌在文字中。

呼叫 IUIAutomationTextRange：：GetText、GetEnclosingElement 和 Move 方法會導致下表所述的行為。

Table

表格範例 1：從儲存格的內容取得文字容器

下表會從儲存格的內容取得文字容器。

包含影像的儲存格	包含文字的儲存格
	X
	Y
	Z

呼叫 IUIAutomationGridPattern：：GetItem、IUIAutomationTextPattern：：RangeFromChild 和 IUIAutomationTextRange：：GetEnclosingElement 方法會導致下表所述的行為。

呼叫的方法	結果
IUIAutomationGridPattern：：GetItem 搭配參數 （0， 0）。	傳回代表數據表單元格內容的 使用者介面自動化 專案，在此案例中，專案是文字控件。
iuiautomationtextpattern：：rangefromchild	會傳回影像 的範圍。
上一個 IUIAutomationTextPattern：：RangeFromChild 方法所傳回物件的 GetEnclosingElement。	傳回代表表格單元格的 使用者介面自動化 專案。 在此情況下，元素是支援 TableItem 控制項模式的文字控制件。
先前 GetEnclosingElement 方法所傳回之物件的 IUIAutomationTextRange：：GetEnclosingElement。	傳回代表數據表的 使用者介面自動化 專案。
先前 GetEnclosingElement 方法所傳回之物件的 IUIAutomationTextRange：：GetEnclosingElement。	傳回代表文字提供者本身的 使用者介面自動化 專案。

表格範例 2：取得儲存格的文字內容

上述範例中的表格會取得儲存格的文字內容。

呼叫 IUIAutomationGridPattern：：GetItem 和 IUIAutomationTextPattern：：RangeFromChild 方法會導致下表所述的行為。

藉由 TextUnit_Line移動檔時，如果文字範圍輸入內嵌表格，則儲存格中的每個文字行都應該視為一行。

相關主題

概念圖

• 關於文字和 TextRange 控制件模式
• 使用者介面自動化 文字屬性
• UI 自動化控制項模式概觀
• 文字內容的 使用者介面自動化 支援