VisualTreeHelper 類別

定義

命名空間:

Microsoft.UI.Xaml.Media

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

public ref class VisualTreeHelper sealed

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 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(Microsoft.UI.Xaml.WinUIContract), 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

範例

以下是公用程式函式的範例，可以從可視化樹狀結構中複製特定類型的子專案清單。 它會使用 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 值一樣簡單的作業) 也一樣。

方法

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

另請參閱

• XAML 控制項範本
• XAML 命名範圍