共用方式為

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

  • 發行項

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

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

注意

這與元件物件模型 （COM） OLE 定義不同（請參閱 內嵌物件），其中元素是在一個應用程式中建立，並在另一個應用程式中內嵌或連結。 物件是否可以在其原始應用程式中編輯，在 使用者介面自動化 的內容中無關緊要。

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

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

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

容器元素

非容器專案

  • Calendar
  • 下拉式方塊
  • DataGrid
  • 文件
  • 編輯
  • 群組
  • 頁首
  • HeaderItem
  • 清單​​
  • 功能表
  • MenuBar
  • 窗格
  • SplitButton
  • 定位字元
  • Table
  • 工具列
  • 樹狀結構
  • TreeItem
  • Window
  • 連結
  • CheckBoxes
  • Button

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

顯示內嵌數據表和影像之文件的圖例

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

具有內嵌物件之檔的UI自動化內容檢視表

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

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

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

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

物件 相容的內嵌物件 不相容的內嵌物件
非 TextPattern 內嵌物件 Microsoft Edge 中的按鈕
Microsoft Edge 中的數據表		 Microsoft XAML 架構中的 RichTextBlock 按鈕
Microsoft Edge 中具有替換文字的影像
Microsoft XAML 架構中 RichTextBlock 中 ListItems 的 ListView
TextPattern 內嵌物件 Microsoft Edge 中類型 「text」 的輸入控件
Word 檔中的表格		 Microsoft Word 檔中的 TextBox 元素

公開內嵌物件

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

在 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」 具有 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 方法會導致下表所述的行為。

呼叫的方法 結果
IUIAutomationTextRange：：GetText 傳回字串「URL https://www.microsoft.com 內嵌在文字中」。
IUIAutomationTextRange：：GetEnclosingElement 傳回最內層的 使用者介面自動化 專案，以括住文字範圍，在此案例中，代表文字提供者本身的自動化專案。
IUIAutomationTextRange：：GetChildren 傳回代表超連結控制件的 使用者介面自動化 專案。
IUIAutomationTextPattern：：RangeFromChild，其中上一個 IUIAutomationTextRange：：GetChildren 方法會傳回 使用者介面自動化 元素。 傳回代表 “https://www.microsoft.com"” 的範圍。

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

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

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

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

呼叫的方法 結果
IUIAutomationTextRange：：GetText 傳回字串 "www"。
IUIAutomationTextRange：：GetEnclosingElement 傳回括住文字範圍的最內部 使用者介面自動化 專案;在此案例中為超連結控件。
IUIAutomationTextRange：：GetChildren 傳回 NULL，因為文字範圍不會跨越整個 URL 字串。

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

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

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

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

呼叫的方法 結果
IUIAutomationTextRange：：GetText 傳回字串 "The URL"。
IUIAutomationTextRange：：GetEnclosingElement 傳回最內層的 使用者介面自動化 專案，以括住文字範圍，在此案例中，代表文字提供者本身的專案。
IUIAutomationTextRange：：Move 將文字範圍範圍移至「https://」，因為超連結的文字是由個別單字所組成。 在此情況下，並未將超連結視為單一物件。
URL {http} 內嵌在文字中。

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

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

{影像 航天飛機的圖例 內嵌在文字中}。

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

呼叫的方法 結果
IUIAutomationTextRange：：GetText 傳回字串「影像內嵌在文字中」。 與影像相關聯的任何 ALT 文字都不會包含在文字數據流中。
IUIAutomationTextRange：：GetEnclosingElement 傳回最內層的 使用者介面自動化 專案，以括住文字範圍，在此案例中為代表文字提供者本身的專案。
IUIAutomationTextRange：：GetChildren 傳回代表影像控件的 使用者介面自動化 專案。
IUIAutomationTextPattern：：RangeFromChild，其中 使用者介面自動化 元素是由先前的 IUIAutomationTextRange：：GetChildren 方法傳回。 傳回變質範圍。

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

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

{影像} 航天飛機的圖例 內嵌在文字中。

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

呼叫的方法 結果
IUIAutomationTextRange：：GetText 傳回字串 "The image"。
IUIAutomationTextRange：：GetEnclosingElement 傳回最內層的 使用者介面自動化 專案，以括住文字範圍，在此案例中，代表文字提供者本身的專案。
IUIAutomationTextRange：：Move 搭配 參數 （TextUnit_Word， 2）。 將文字範圍移至 "is"。 由於只有以文字為基礎的內嵌物件會被視為文字數據流的一部分，因此此範例中的影像不會影響 IUIAutomationTextRange：：Move 或其傳回值，在此案例中為 2。

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 方法會導致下表所述的行為。

呼叫的方法 結果
具有參數的 IUIAutomationGridPattern：：GetItem （1,1）。 會傳回代表表格單元格內容的 使用者介面自動化 專案。 在此情況下，元素是文字控件。
IUIAutomationTextPattern：：RangeFromChild，其中 使用者介面自動化 專案是上一個 IUIAutomationGridPattern：：GetItem 方法所傳回的物件。 傳回 "Y"。

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

概念圖