共用方式為

TextPattern 和嵌入式物件概觀

備註

本檔適用於想要使用 System.Windows.Automation 命名空間中定義的受控UI自動化類別的 .NET Framework 開發人員。 如需 UI 自動化的最新資訊，請參閱 Windows 自動化 API：使用者介面自動化。

本概觀描述Microsoft UI 自動化如何在文字檔或容器內公開內嵌的物件或子專案。

在 UI 自動化中，嵌入物件是具有非文字界限的任何元素，例如影像、超連結、表格或文件類型，如 Microsoft Excel 電子表格或 Microsoft Windows Media 檔案。 這與標準的定義不同，其中元素是在一個應用程式中建立，並在另一個應用程式中內嵌或連結。 在 UI 自動化的內容中，物件是否可以在其原始應用程式中進行編輯無關緊要。

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

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

文字容器中的影像內嵌數據表 含有數據表、影像和超連結內嵌物件的文字容器範例

上述範例的內容檢視 前述文字容器部分內容檢視的範例

使用 TextPattern 和 TextPatternRange 公開內嵌物件

搭配使用， TextPattern 控件模式類別和 TextPatternRange 類別會公開方法與屬性，以利巡覽和查詢內嵌物件。

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

由內嵌物件跨越的文字範圍。 具有內嵌物件及其範圍範圍的文字數據流範例

當需要遍歷文字範圍的內容時，在幕後需要一系列步驟，才能讓 Move 方法順利執行。

  1. 文字範圍已被正規化；意味著，文字範圍會折疊為Start 端點的退化範圍，使End 端點變得多餘。 在文字範圍跨越 TextUnit 界限的情況下，必須移除模棱兩可：例如，當“{”和“}”是文字範圍的端點。

  2. 產生的範圍會移動至 DocumentRange 中，向後到達所要求 TextUnit 界限的開頭。

  3. 範圍會依要求的界限數目DocumentRange往前或向後TextUnit移動。

  4. 然後，範圍會從退化的範圍狀態通過將 End 端點移動到一個要求的 TextUnit 邊界來進行擴展。

Move 和 ExpandToEnclosingUnit 的範圍調整 Move() 和 ExpandToEnclosingUnit() 的文字範圍調整範例

常見案例

下列各節提供涉及內嵌物件之最常見案例的範例。

範例說明：

{ = Start

} = End

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

{The URL https://www.microsoft.com is embedded in text}.

方法被呼叫 結果
GetText 傳回 The URL https://www.microsoft.com is embedded in text 字串。
GetEnclosingElement 傳回封入文字範圍的最內層 AutomationElement; 在此案例中，指的是表示文字提供者本身的 AutomationElement。
GetChildren 傳 AutomationElement 回 ，表示超連結控制件。
RangeFromChild 其中 AutomationElement 是上一 GetChildren 個方法所傳回的物件。 傳回代表 https://www.microsoft.com的範圍。

範例 2 - 部分包含內嵌超連結的文字範圍

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

方法被呼叫 結果
GetText 傳回字串 "www"。
GetEnclosingElement 會傳回括住文字範圍的最 AutomationElement 內層，在此案例中為超連結控件。
GetChildren null傳回 ，因為文字範圍不會跨越整個 URL 字串。

範例 3 - 部分跨越文字容器內容的文字範圍。 此文字容器有不屬於此文字範圍的內嵌文字超連結。

{The URL} [https://www.microsoft.com](https://www.microsoft.com) is embedded in text.

方法被呼叫 結果
GetText 傳回字串 "The URL"。
GetEnclosingElement 傳回封入文字範圍的最內層 AutomationElement; 在此案例中，指的是表示文字提供者本身的 AutomationElement。
Move 具有參數（TextUnit.Word，1）。 將文字範圍範圍移至 「HTTP」，因為超連結的文字是由個別單字所組成。 在此情況下，並未將超連結視為單一物件。

URL {[http]} 內嵌在文字中。

圖片

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

{影像 內嵌影像範例 嵌入於文字中}。

方法被呼叫 結果
GetText 傳回字串「The 內嵌在文字中」。 與影像相關聯的任何 ALT 文字都不能包含在文字數據流中。
GetEnclosingElement 傳回封入文字範圍的最內層 AutomationElement; 在此案例中，指的是表示文字提供者本身的 AutomationElement。
GetChildren 回傳AutomationElement，表示影像控件。
RangeFromChild 其中 AutomationElement 是上一 GetChildren 個方法所傳回的物件。 會傳回代表「內嵌影像範例」的退化範圍。

範例 2 - 部分跨越文字容器內容的文字範圍。 此文字容器有不屬於此文字範圍的內嵌影像。

{image} 內嵌影像範例 內嵌在文字中。

方法被呼叫 結果
GetText 傳回字串「圖片」。
GetEnclosingElement 傳回封入文字範圍的最內層 AutomationElement; 在此案例中，指的是表示文字提供者本身的 AutomationElement。
Move 具有參數（TextUnit.Word，1）。 將文字範圍移至 "is "。 由於只有以文字為基礎的內嵌物件會被視為文字數據流的一部分，因此此範例中的影像不會影響Move或其傳回值（在此案例中為1）。

表

用於範例的數據表

包含影像的儲存格 包含文字的儲存格
內嵌影像範例 X
內嵌影像範例 2 是
內嵌影像範例 3

Z 的圖片		 Z

範例 1 - 從儲存格的內容取得文字容器。

呼叫的方法 結果
GetItem 含參數 （0,0） 傳回 AutomationElement，該元素代表表格單元格的內容；在此情況下，該元素是一個文字控制項。
RangeFromChild 其中 AutomationElement 是上一 GetItem 個方法所傳回的物件。 傳回涵蓋影像 內嵌影像範例 的範圍。
GetEnclosingElement 針對上一 RangeFromChild 個方法所傳回的物件。 返回代表表格單元格的 AutomationElement；在這種情況下，該元素是一個支援 TableItemPattern 的文字控制項。
GetEnclosingElement 針對上一 GetEnclosingElement 個方法所傳回的物件。 回傳代表資料表的AutomationElement。
GetEnclosingElement 針對上一 GetEnclosingElement 個方法所傳回的物件。 傳回 AutomationElement，表示文字提供者本身。

範例 2 - 取得儲存格的文字內容。

呼叫的方法 結果
GetItem 參數為 （1,1）。 傳回 AutomationElement，該元素代表表格單元格的內容；在此情況下，該元素是一個文字控制項。
RangeFromChild 其中 AutomationElement 是上一 GetItem 個方法所傳回的物件。 傳回 "Y"。

另請參閱

  • Last updated on