TextPattern 和 Embedded 物件概觀
注意
本文件適用對象為 .NET Framework 開發人員，其想要使用 System.Windows.Automation 命名空間中定義的受控 UI 自動化類別。 如需 UI 自動化的最新資訊，請參閱 Windows 自動化 API：UI 自動化。
本概觀描述 Microsoft UI 自動化如何在文字文件或容器內公開內嵌物件或子元素。
在 UI 自動化中，內嵌物件是任何具有非文字界限的元素；例如，影像、超連結、表格或文件類型 (如 Microsoft Excel 試算表或 Microsoft Windows Media 檔案)。 這不同於下列標準定義：元素建立於一個應用程式中，並內嵌或連結在另一個應用程式中。 物件是否可以在其原始應用程式中進行編輯與 UI 自動化的內容無關。
內嵌物件和 UI 自動化樹狀目錄
內嵌物件會被視為 UI 自動化樹狀結構的控制項檢視內的個別元素元素。 這些元素會公開成為文字容器的子系，以便透過與 UI 自動化中其他控制項相同的模式進行存取。
表格、影像和超連結內嵌物件的文字容器範例
上述文字容器之一部分的內容檢視範例
使用 TextPattern 和 TextPatternRange 公開內嵌物件
TextPattern 控制項模式類別和 TextPatternRange 類別搭配使用，可公開方法和屬性，以便瀏覽和查詢內嵌物件。
在 UI 自動化樹狀結構的控制項檢視和內容檢視 (例如超連結或表格儲存格) 中，文字容器和內嵌物件的文字內容 (或內部文字) 會公開為單一連續的文字資料流； 物件界限會被忽略。 如果使用者介面自動化用戶端為了以某種方式進行敘述、解譯或分析而擷取文字，則應檢查特殊案例 (例如具有文字內容或其他內嵌物件的表格) 的文字範圍。 呼叫 GetChildren 以取得每個內嵌物件的 AutomationElement ，然後呼叫 RangeFromChild 以取得每個元素的文字範圍，即可達成。 這會以遞迴方式進行，直到擷取所有的文字內容為止。
具有內嵌物件及其範圍的文字資料流範例
如需周遊文字範圍的內容，則應在幕後執行一連串的步驟，才能成功執行 Move 方法。
文字範圍已正規化；也就是，文字範圍已在 Start 端點摺疊為變質範圍，以致 End 端點變成多餘的。 在文字範圍跨越 TextUnit 界限的情況下，這是消除語意模糊的必要步驟：例如，
{The URL https://www.microsoft.com is embedded in text，其中 "{" 和 "}" 是文字範圍端點。結果產生的範圍會在 DocumentRange 中向後移至所要求 TextUnit 界限的開頭。
範圍會在 DocumentRange 中依所要求的 TextUnit 界限數目向前或向後移動。
如何針對 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 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)。 |
Table
範例使用的資料表
| 包含影像的儲存格 | 包含文字的儲存格 |
|---|---|
|
X |
 |
Y |
 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"。 |