VisualTreeHelper クラス

定義

名前空間:

Windows.UI.Xaml.Media

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

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 を使用します。 再帰を使用して、中間コンテナー内の入れ子のレベルに関係なく要素を見つけることができます。 また、型比較を拡張してサブタイプを Type の一致と見なす 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 マークアップとビジュアル ツリーは、マークアップ用に設計されており、マークアップ定義時の使いやすさが高いため、ノード for node と完全には一致しません。そのため、追加の要素が含まれる場合があります。 たとえば、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 として返します。有用な操作を行うには、その要素をキャストする必要があります ( 名前 の値を確認する操作と同じくらい単純な場合でも)。

以前のバージョンの注意事項

Windows 8

UI スレッド処理

Windows 8間違った (現在の) UI スレッド上のオブジェクトを参照していた VisualTreeHelper 関数呼び出しを許可します。 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 の暗黙的なスタイルを提供するか、VisualTreeHelper を使用してツリーを歩いて、この内部で作成された ScrollViewer を見つけて実行時に変更することで、この動作をアプリで予測している可能性があります。 Windows 8.1用にコンパイルされたアプリの場合、そのコードは役に立ちません。

Windows 8 用にコンパイルしたアプリは、Windows 8.1 上で実行しても Windows 8 のときと同じ動作になります。

バージョン履歴

Windows のバージョン	SDK バージョン	追加された値
1903	18362	GetOpenPopupsForXamlRoot

メソッド

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)	開いているすべてのポップアップ コントロールのコレクションをターゲット Window から取得 します。
GetOpenPopupsForXamlRoot(XamlRoot)	ターゲット XamlRoot から開いているすべてのポップアップ コントロールのコレクションを取得します。
GetParent(DependencyObject)	ビジュアル ツリー内のオブジェクトの親オブジェクトを返します。

こちらもご覧ください

• クイック スタート: コントロール テンプレート
• XAML 名前スコープ
• 機能別コントロール