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

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

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

內嵌物件和 UI 自動化樹狀結構

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

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

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

上一份文件的 UI 自動化內容檢視如以下圖所示。

"相容的" 和 "不相容的" 內嵌物件

某些 使用者介面自動化 提供者會針對所包含的每個 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」和「here」這幾個字。其中，「link」具有 TextPattern 物件作為封閉元素，並且 link 物件作為其子元素。
• 在 Character 單位的情況下，物件是包圍元素（這類文字單位不應該有子元素）。
• 註釋物件不應表示為內嵌物件。 例如，在共同撰寫的文件中存在其他作者指定者。
• 內嵌物件至少佔用一個游標位置，註釋只是元數據。
• 每個物件界限（開始和結束）都會以 TextPattern 檔範圍中的格式中斷表示。
• 針對 HTML，每個 html 標記不一定會產生 使用者介面自動化 物件。 例如，強調標記內 的內容不需要表示為元素，而是以文字數據流表示，其中UIA_IsItalicAttributeId會傳回 TRUE。
• 起始端點是包含的，並且是偏好的端點，而結束端點是不包括的。 當範圍變質，而開始和結束端點屬於該範圍的相同位置時，這非常有用。

比較內嵌物件

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

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

內嵌的文字模式物件和文檔文字單位 (TextPattern objects and 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 方法會導致下表所述的行為。

表格

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

以下表格將從儲存格的內容中獲取文本容器。

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

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

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

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

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

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

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

相關主題

概念

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