VisualTreeHelper クラス

定義

名前空間:: Microsoft.UI.Xaml.Media

重要

一部の情報は、リリース前に大きく変更される可能性があるプレリリースされた製品に関するものです。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。

編集

アプリのビジュアルツリー内のオブジェクトリレーションシップ (子オブジェクト軸または親オブジェクト軸に沿って) を走査するために使用できるユーティリティメソッドを提供します。

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 拡張メソッドも使用します。

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 の概要」を参照してください。

ビジュアルツリーは UI レンダリングプロセス用に内部的に使用されますが、コントロールテンプレートの記述や置換、実行時のコントロールの構造とパーツの分析など、特定のシナリオではビジュアルツリーの構造を把握することが重要です。これらのシナリオでは、Windows ランタイムは、より一般化された方法でビジュアルツリーを調べることができる VisualTreeHelper API を提供します。 (理論的にはオブジェクト固有の親プロパティと子プロパティを使用してこのようなツリーを構築することもできますが、各要素がサポートするプロパティを正確に把握する必要があり、検出や管理が困難です)。

通常、複数の VisualTreeHelper API 呼び出しを組み合わせて、独自のアプリのシナリオに固有の方法でビジュアルツリーを調査する独自のヘルパー関数を記述します。

ビジュアルツリーの走査

オブジェクトツリーの走査 (ツリーの ウォークと口語的に呼ばれることもあります) は、オブジェクトモデルの一般的な手法です。子オブジェクト (通常はコレクション) を参照するプロパティまたは親オブジェクトへの親リレーションシップを使用します (通常、これはコレクション内から行われ、コレクション自体を返します)。プロセスの大まかな説明として、子プロパティと親プロパティ (またはヘルパーメソッド) の連続を呼び出して、探していたオブジェクトを含む値を取得するまでオブジェクトツリーの軸を移動します。原則として、ツリーの構造を広範囲に照会する必要がないように、XAML でコンテンツを構築できる必要があります。ツリーを走査する必要を回避するには、XAML 要素を作成する XAML マークアップの x:Name / Name 属性の値を XAML 要素に指定する必要があります。これにより、実行時のコードアクセスに使用できる即時参照が作成されます。これは、ツリーを歩くよりもオブジェクト参照を取得するためのエラーが発生しやすい手法です。または、XAML ではなくコードを使用してオブジェクトを作成する場合は、実行時にオブジェクト参照を保持するプライベートフィールドまたは変数を宣言する必要があります。通常、独自のコードで作成されたオブジェクトを見つけるためにツリーを走査する必要はありません。

ただし、オブジェクトに名前を付け、オブジェクト参照をスコープ内に保持することは不可能または実用的な場合があります。このようなシナリオの 1 つは、ユーザーによって提供されるか、データバインディングによって提供される動的コンテンツを追加するか、ビューモデルとビジネスオブジェクトを使用する場合です。このような場合、追加された項目の数やコントロールとその子の構造を常に予測することはできません。もう 1 つのシナリオは、コントロールの適用されたテンプレート、またはコントロールまたは発表者のコンテンツの複合セクションを調べることです。

0 以外の値に対して GetChildrenCount を使用し、 GetChild を使用して特定のインデックスを要求すると、ツリーを (ルートから離れて) 下方向に走査できます。要素を特定の UIElement サブタイプとしてキャストしようとしている場合は、try/catch 手法または同等の手法を使用する必要がある場合があります。一般に、VisualTreeHelper API は要素を DependencyObject として返します。有用な操作を行うには( 名前の値をチェックする操作と同じくらい単純な場合でも)、それをキャストする必要があります。

メソッド

名前	説明
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)	ビジュアルツリー内のオブジェクトの親オブジェクトを返します。

適用対象

こちらもご覧ください

フィードバック

このページはお役に立ちましたか?