TextPattern 和 Embedded 物件概觀

發行項
08/12/2011

注意事項
這份文件適用於想要使用 System.Windows.Automation 命名空間中定義之 Managed UI Automation 類別的 .NET Framework 開發人員。如需 UI Automation 的最新資訊，請參閱 Windows Automation API：使用者介面自動化 (英文)。

本概觀說明 Microsoft UI Automation如何公開文字文件或容器內嵌的物件或子項目。

在 UI Automation中，內嵌物件是指任何有非文字界限的項目，例如影像、超連結、資料表，或是諸如 Microsoft Excel 試算表或 Microsoft Windows Media 檔案等文件類型。這與標準定義不同，在標準定義中，則是指在一個應用程式中建立項目，再將該項目內嵌或連結到另一個應用程式。無論物件在原始應用程式可否編輯，都與 UI Automation的內容無關。

這個主題包含下列章節。

內嵌物件和 UI 自動化樹狀目錄
使用 TextPattern 和 TextPatternRange 公開內嵌物件
常見案例
相關主題

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

內嵌物件會被視為 UI Automation樹狀目錄之控制項檢視內的個別項目。這些物件會公開為文字容器的子項，因此可以透過與 UI Automation其他控制項相同的模型存取。

有資料表、影像和超連結內嵌物件的文字容器範例

影像位於文字容器中的內嵌式資料表

上面文字容器一部分的內容檢視範例

前述範例的內容檢視

使用 TextPattern 和 TextPatternRange 公開內嵌物件

一起使用 TextPattern 控制項模式類別和 TextPatternRange 類別時，可公開方便巡覽和查詢內嵌物件的方法和屬性。

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

文字資料流與內嵌物件及其範圍的範例

內嵌之物件合併的文字範圍。

當有必要周遊文字範圍的內容時，幕後會進行一連串的步驟，讓 Move 方法能夠成功執行。

文字範圍已正規化，也就是說，文字範圍已收合成 Start 端點的變質範圍，使 End 端點變得多餘。此步驟的目的是要消除在文字範圍跨 TextUnit 界限時產生的模稜兩可，以 "{The U}RL https://www.microsoft.com is embedded in text" 為例，"{" 和 "}" 就是文字範圍的端點。
結果範圍會在 DocumentRange 中向後移動至要求的 TextUnit 界限開頭。
範圍已根據要求的 TextUnit 界限數，在 DocumentRange 中前後移動。
範圍接著再移動 End 端點一個要求的 TextUnit 界限，從變質範圍狀態擴大。

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

由 Move 和 ExpandToEnclosingUnit 進行的範圍調整

常見案例

下列章節將以範例說明內嵌物件最常見的案例。

顯示範例的圖例：

{ = Start

} = End

Hyperlink

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

{URLhttps://www.microsoft.com 內嵌於文字中}。

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

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

URL http://{www} 內嵌於文字中。

呼叫的方法	結果
GetText	傳回字串 "www"。
GetEnclosingElement	傳回括住文字範圍的最內層 AutomationElement；在這個案例中就是超連結控制項。
GetChildren	傳回 null，因為文字範圍並未跨整個 URL 字串。

範例 3 - 部分跨文字容器內容的文字範圍。這個文字容器有一個內嵌文字超連結，但它不屬於文字範圍的一部分。

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

呼叫的方法	結果
GetText	傳回字串 "The URL"。
GetEnclosingElement	傳回封入文字範圍的最內層 AutomationElement；在這個案例中就是代表文字提供者本身的 AutomationElement。
Move 和參數 (TextUnit.Word, 1)	將文字範圍移至 "http"，因為超連結的文字是由個別單字組成。在此情況下，超連結不會視為單一物件。 URL {} 內嵌於文字中。

GetText

傳回字串 "The URL"。

GetEnclosingElement

傳回封入文字範圍的最內層 AutomationElement；在這個案例中就是代表文字提供者本身的 AutomationElement。

Move 和參數 (TextUnit.Word, 1)

將文字範圍移至 "http"，因為超連結的文字是由個別單字組成。在此情況下，超連結不會視為單一物件。

URL {} 內嵌於文字中。

Image

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

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

呼叫的方法	結果
GetText	傳回字串 "The is embedded in text"。與影像相關的任何 ALT 文字不應視為會包含在文字資料流中。
GetEnclosingElement	傳回封入文字範圍的最內層 AutomationElement；在這個案例中就是代表文字提供者本身的 AutomationElement。
GetChildren	傳回代表影像控制項的 AutomationElement。
RangeFromChild，其中 AutomationElement 是前一個 GetChildren 方法所傳回的物件	傳回表示 "" 的變質範圍。

範例 2 - 部分跨文字容器內容的文字範圍。這個文字容器有一個內嵌影像，但它不屬於文字範圍的一部分。

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

呼叫的方法	結果
GetText	傳回字串 "The image"。
GetEnclosingElement	傳回封入文字範圍的最內層 AutomationElement；在這個案例中就是代表文字提供者本身的 AutomationElement。
Move 和參數 (TextUnit.Word, 1)	將文字範圍移至 "is "。因為只有文字基礎的內嵌物件會被視為文字資料流的一部分，所以這個範例中的影像不會影響 Move 或其傳回值 (此範例為 1)。

表格

範例使用的資料表

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

內嵌影像範例

內嵌影像範例 2

內嵌影像範例 3

Z 的影像

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

呼叫的方法	結果
GetItem 和參數 (0,0)	傳回表示資料表儲存格內容的 AutomationElement；在這個案例中，項目是文字控制項。
RangeFromChild，其中 AutomationElement 是前一個 GetItem 方法所傳回的物件	傳回跨影像的範圍。
前一個 RangeFromChild 方法所傳回之物件的 GetEnclosingElement	傳回表示資料表儲存格的 AutomationElement；在這個案例中，項目是支援 TableItemPattern 的文字控制項。
前一個 GetEnclosingElement 方法所傳回之物件的 GetEnclosingElement	傳回表示資料表的 AutomationElement。
前一個 GetEnclosingElement 方法所傳回之物件的 GetEnclosingElement	傳回表示文字提供者本身的 AutomationElement。

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

呼叫的方法	結果
GetItem 和參數 (1,1)	傳回表示資料表儲存格內容的 AutomationElement；在這個案例中，項目是文字控制項。
RangeFromChild，其中 AutomationElement 是前一個 GetItem 方法所傳回的物件	傳回 "Y"。