VisualTreeHelper 類別

參考

定義

命名空間:: Windows.UI.Xaml.Media

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

編輯

提供公用程式方法，可用來周遊應用程式視覺化樹狀結構中子物件或父物件座標軸 (的物件關聯性) 。

public ref class VisualTreeHelper sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class VisualTreeHelper final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class VisualTreeHelper

Public NotInheritable Class VisualTreeHelper

繼承: Object Platform::Object IInspectable VisualTreeHelper

屬性: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v1.0 引進)

範例

以下是公用程式函式的範例，可以從視覺化樹狀結構中複製特定類型的子專案清單。它會使用 GetChildrenCount 和 GetChild的基本周遊方法。它會使用遞迴，因此無論中繼容器中的巢狀層級為何，都可以找到元素。它也會使用System.Reflection的IsSubclassOf擴充方法，擴充類型比較，以將子類型視為與 Type相符的專案。

internal static void FindChildren<T>(List<T> results, DependencyObject startNode)
  where T : DependencyObject
{
    int count = VisualTreeHelper.GetChildrenCount(startNode);
    for (int i = 0; i < count; i++)
    {
        DependencyObject current = VisualTreeHelper.GetChild(startNode, i);
        if ((current.GetType()).Equals(typeof(T)) || (current.GetType().GetTypeInfo().IsSubclassOf(typeof(T))))
        {
            T asType = (T)current;
            results.Add(asType);
        }
        FindChildren<T>(results, current);
    }
}

備註

視覺化樹狀結構

VisualTreeHelper 類別的目的是協助您探索您要在物件的執行時間樹狀目錄中尋找的物件，但您的案例沒有更直接的物件關聯性 API。有時候，您不知道物件的確切類型或名稱。或者，您可能知道特定物件出現在樹狀結構中的某處，但您不知道確切的位置。在這些類型的案例中，VisualTreeHelper 很有説明，因為您可以遞迴地尋找視覺化樹狀結構中的所有物件，然後查看此集合，並根據您的準則尋找相符專案。

應用程式的視覺化樹狀結構可以概念化為應用程式物件和屬性之較大物件樹狀結構的篩選標記法。只有具有轉譯含意的物件會出現在視覺化樹狀結構中。例如，集合類別不會是視覺化樹狀結構的一部分。相反地，視覺化樹狀結構會將任何集合抽象化為「子系」概念。

不過，視覺化樹狀結構也可以包含未表示為頁面 XAML 標記中 XAML 元素的物件。這是因為視覺化樹狀結構會新增物件，這些物件是控制項的複合部分。這些控制群組件可能來自套用的控制項範本，通常是來自資源字典專案或簡報者的 XAML。

XAML 標記和視覺化樹狀結構與節點對節點完全不相符，因為 XAML 是針對標記所設計，而且在標記定義期間容易使用，因此有時會有額外的元素。例如，XAML 具有屬性元素，如果某個元素位於另一個元素內巢狀，則會設定屬性值。在視覺化樹狀結構中，這看起來像是另一個物件所設定之物件上的屬性。 XAML 也有內容屬性的概念，其中正在設定的屬性未在標記中明確指定。如需 XAML 的特定術語和規則的詳細資訊，請參閱 XAML 概觀。

視覺化樹狀結構會在內部用於 UI 轉譯程式，但瞭解視覺化樹狀結構對於某些案例很重要，例如撰寫或取代控制項範本，或在執行時間分析控制項的結構和元件。在這些案例中，Windows 執行階段會提供 VisualTreeHelper API，以更一般化的方式檢查視覺化樹狀結構。 (您理論上也可以使用物件特定的父系和子系屬性來建構這類樹狀結構，但您必須確切知道每個支援的屬性，而且很難探索或管理。)

您通常會結合數個 VisualTreeHelper API 呼叫來撰寫自己的協助程式函式，以專屬於您應用程式案例的特定方式調查視覺化樹狀結構。

周遊視覺化樹狀結構

周遊物件樹狀結構 (有時已知 ，因為樹 狀結構) 是物件模型中的常見技術。您可以使用參考子物件的屬性 (通常是集合) 或包含物件的父關聯性 (通常是從集合內完成，並傳回集合本身) 。做為程式的粗略描述，您可以呼叫連續的子屬性和父屬性，或是協助程式方法，以巡覽物件樹狀結構的軸，直到您擷取包含您要尋找之物件的值為止。一般而言，您應該能夠在 XAML 中建構內容，讓您不需要大量查詢樹狀結構。為了避免需要周遊樹狀結構，您應該為 XAML 元素提供建立樹狀結構之 XAML 標記中x：Name / 屬性的值。這會建立可供執行時間程式碼存取的立即參考，這是比樹狀結構更不容易取得物件參考的錯誤技巧。或者，如果您要透過程式碼而非 XAML 建立物件，您應該宣告在執行時間保留物件參考的私人欄位或變數。通常不需要周遊樹狀結構，即可尋找在您自己的程式碼中建立的物件。

不過，在某些情況下，無法或實際地提供物件名稱，並將物件參考保留在範圍內。其中一種案例是，如果您要新增由使用者提供的動態內容，或由資料系結提供，或使用檢視模型和商務物件。在這些情況下，您無法一律預測加入的專案數或控制項及其子系的結構。另一個案例是檢查控制項的已套用範本，或控制項或簡報者內容的複合區段。

將樹狀結構向下周遊 (離開根) 多個層級，可以使用 GetChildrenCount 進行非零值，然後 GetChild 要求特定索引。如果您嘗試將元素轉換成特定UIElement子類型，您可能必須使用try/catch技術或對等專案。一般而言，VisualTreeHelper API 會以 DependencyObject 的形式傳回元素，而且您必須轉換它，才能執行任何有用的 (，即使是像檢查其 Name 值一樣簡單的作業) 也一樣。

舊版的注意事項

Windows 8

UI 執行緒

Windows 8允許在錯誤 (上參考物件的 VisualTreeHelper 函式呼叫，而不是目前的) UI 執行緒。從 Windows 8.1 開始，如果函式不是從目前的 UI 執行緒呼叫，就會擲回例外狀況。考慮此新行為應該是非常不常見的應用程式移轉案例;一開始很難跨執行緒取得 UI 元素。

針對Windows 8編譯但執行于Windows 8.1的應用程式會使用Windows 8.1行為，而且會在 VisualTreeHelper 函式呼叫上特別擲回，而不是在任何使用跨執行緒物件的下游應用程式程式碼上擲回。

螢幕小鍵盤的應用程式 UI

Windows 8有內部實作的邏輯，會在使用者叫用螢幕小鍵盤時，將ScrollViewer與整體應用程式 UI 產生關聯。此螢幕小鍵盤是使用者透過簡易存取中心要求的特定協助工具功能。如果系統偵測到沒有鍵盤裝置，它與可在文字輸入控制項的應用程式 UI 中顯示的軟式鍵盤不同。這裡的內部 ScrollViewer 是讓捲動應用程式所在的區域，如果因為鍵盤佔用 UI 空間而強制捲動，就能夠捲動它。

從Windows 8.1開始，當螢幕小鍵盤出現時，系統仍會有 UI/版面配置行為，但不再使用此內部建立的 ScrollViewer。而是使用應用程式程式碼無法變更或檢查的專用內部控制項。

此行為變更的大部分層面都不會影響應用程式。不過，您的應用程式可能已預期此行為，方法是為ScrollViewer提供隱含的 Style來變更版面配置，或使用 VisualTreeHelper 來逐步執行樹狀結構，以在執行時間尋找此內部建立的ScrollViewer並加以改變。針對針對Windows 8.1編譯的應用程式，該程式碼將無法使用。

針對 Windows 8 編譯但在 Windows 8.1 上執行的應用程式會繼續使用 Windows 8 的行為。

版本歷程記錄

Windows 版本	SDK 版本	新增值
1903	18362	GetOpenPopupsForXamlRoot

方法

DisconnectChildrenRecursive(UIElement)	明確地從目標 UIElement移除所有參考，目標是清除參考週期。
FindElementsInHostCoordinates(Point, UIElement, Boolean)	擷取一組物件，這些物件位於應用程式 UI 的指定 x-y 座標點內。物件集代表共用該點之視覺化樹狀結構的元件。
FindElementsInHostCoordinates(Point, UIElement)	擷取一組物件，這些物件位於應用程式 UI 的指定 x-y 座標點內。物件集代表共用該點之視覺化樹狀結構的元件。
FindElementsInHostCoordinates(Rect, UIElement, Boolean)	擷取一組物件，這些物件位於應用程式 UI 的指定 Rect 框架內。物件集代表共用矩形區域之視覺化樹狀結構的元件，而且可能包含過度繪製的專案。
FindElementsInHostCoordinates(Rect, UIElement)	擷取一組物件，這些物件位於應用程式 UI 的指定 Rect 框架內。物件集代表共用矩形區域之視覺化樹狀結構的元件，而且可能包含過度繪製的專案。
GetChild(DependencyObject, Int32)	使用提供的索引，藉由檢查視覺化樹狀結構，取得所提供物件的特定子物件。
GetChildrenCount(DependencyObject)	傳回視覺化樹狀結構中物件子集合中存在的子係數目。
GetOpenPopups(Window)	從目標視窗擷取所有開啟快顯視窗控制項的集合。
GetOpenPopupsForXamlRoot(XamlRoot)	從目標 XamlRoot擷取所有開啟的快顯控制項集合。
GetParent(DependencyObject)	傳回視覺化樹狀結構中物件的父物件。

適用於

共用方式為