x:Name ディレクティブ

  • [アーティクル]

XAML 名前スコープ内の XAML 定義要素を一意に識別します。 フレームワークで API が提供される場合や、XAML で作成されたオブジェクト グラフに実行時にアクセスする動作が実装される場合に、XAML 名前スコープとその一意モデルを、インスタンス化されたオブジェクトに適用できます。

XAML 属性の使用方法

<object x:Name="XAMLNameValue".../>

XAML 値

値 説明
XAMLNameValue XamlName の文法の制限に準拠する文字列。

解説

x:Name がフレームワークのバッキング プログラミング モデルに適用された後、名前は、コンストラクターによって返されるオブジェクト参照またはインスタンスを保持する変数と同等になります。

x:Name ディレクティブの使用の値は、XAML 名前スコープ内で一意である必要があります。 既定では、.NET XAML サービス API によって使用される場合、プライマリ XAML 名前スコープは、1 つの XAML 運用環境の XAML ルート要素で定義され、その XAML 運用環境に含まれる要素を包含します。 1 つの XAML 運用環境内で発生する可能性のある追加の個別の XAML 名前スコープは、特定のシナリオに対応するようにフレームワークによって定義できます。 たとえば、WPF では、新しい XAML 名前スコープが、その XAML 運用環境で定義されている任意のテンプレートによって定義および作成されます。 XAML 名前スコープの詳細については (WPF 用に記述されていますが、多くの XAML 名前スコープの概念に関連します)、「WPF XAML 名前スコープ」を参照してください。

一般的に、x:Key も使用する状況では x:Name を適用しないでください。 特定の既存のフレームワークによる XAML の実装では、x:Key と x:Name の間に代入の概念が導入されていますが、これは推奨される方法ではありません。 .NET XAML サービスでは、INameScope や DictionaryKeyPropertyAttribute などの名前とキーの情報を処理するときに、このような代入の概念はサポートされません。

x:Name の許可の規則と名前の一意性の強制は、特定の実装フレームワークによって定義される可能性があります。 ただし、.NET XAML サービスで使用できるようにするには、XAML 名前スコープの一意性のフレームワーク定義がこのドキュメントの INameScope 情報の定義と一致している必要があります。また、情報が適用される場所についても同じ規則を使用する必要があります。 たとえば、Windows Presentation Foundation (WPF) の実装では、さまざまなマークアップ要素がリソース ディクショナリ、ページレベルの XAML によって作成された論理ツリー、テンプレート、その他の遅延コンテンツなどの個別の NameScope 範囲に分割され、それらの各 XAML 名前スコープ内で XAML 名の一意性が適用されます。

.NET XAML サービス XAML オブジェクト ライターを使用するカスタム型では、型の x:Name にマップされるプロパティを確立または変更できます。 この動作は、型定義コードの RuntimeNamePropertyAttribute にマップするプロパティの名前を参照することで定義します。 RuntimeNamePropertyAttribute は、型レベルの属性です。

.NET XAML サービスを使用すると、XAML 名前スコープのサポートのバッキング ロジックは、INameScope インターフェイスを実装することによって、フレームワークに依存しない方法で定義できます。

WPF の使用上の注意

XAML、部分クラス、および分離コードを使用する WPF アプリケーションの標準ビルド構成では、指定された x:Name は、マークアップ コンパイル ビルド タスクによって XAML が処理されるときに、基になるコードで作成されるフィールドの名前になります。また、そのフィールドにはオブジェクトへの参照が保持されます。 既定では、作成されたフィールドは internal です。 フィールドへのアクセスを変更するには、x:FieldModifier 属性を指定します。 WPF と Silverlight では、マークアップ コンパイルによって部分クラスのフィールドが定義され、名前を指定されますが、この値は最初は空です。 次に、InitializeComponent という名前の生成されたメソッドが、クラス コンストラクター内から呼び出されます。 InitializeComponent は、部分クラスの XAML 定義部分に存在する各 x:Name 値を入力文字列として使用する FindName 呼び出しで構成されます。 その後、戻り値は、類似する名前のフィールド参照に割り当てられて、XAML 解析から作成されたオブジェクトでフィールド値が設定されます。 InitializeComponent の実行により、x:Name またはフィールド名を使用して実行時のオブジェクト グラフを直接参照できるようになります。このため、XAML 定義オブジェクトへの参照が必要になるたびに FindName を明示的に呼び出す必要はありません。

Microsoft Visual Basic ターゲットが使用され、Page ビルド アクションを含む XAML ファイルが含まれる WPF アプリケーションでは、コンパイル時に個別の参照プロパティが作成されます。このプロパティにより、x:Name を持つすべての要素に WithEvents キーワードが追加されて、イベント ハンドラー デリゲートの Handles 構文がサポートされます。 このプロパティは、常に public に設定されています。 詳細については、「Visual Basic と WPF のイベント処理」を参照してください。

x:Name は、読み込み時に XAML 名前スコープに名前を登録するために WPF XAML プロセッサによって使用されます。これは、ページがビルド アクションによってマークアップ コンパイルされていない場合 (リソース ディクショナリの疎 XAML など) であっても同様です。 この動作の理由の 1 つは、ElementName バインディングに x:Name が必要になる可能性があるためです。 詳細については、「データ バインドの概要」を参照してください。

前述のように、x:Key も使用する状況では x:Name (または Name) を適用しないでください。 WPF ResourceDictionary には、それ自体を XAML 名前スコープとして定義するが、この動作を強制する方法として、INameScope API に対して "実装なし" または null 値を返すという特殊な動作があります。 WPF XAML パーサーによって XAML 定義 ResourceDictionary に Name または x:Name が検出された場合、この名前はどの XAML 名前スコープにも追加されません。 XAML 名前スコープからその名前を見つけようとすると、FindName メソッドによって有効な結果が返されません。

x:Name と Name

多くの WPF アプリケーションのシナリオでは、x:Name 属性の使用を回避できます。これは、いくつかの重要な基底クラス (FrameworkElement や FrameworkContentElement など) の既定の XAML 名前空間で指定されている Name 依存関係プロパティによって、この同じ目的が実現されるためです。 フレームワーク レベルで Name プロパティを持たない要素へのコード アクセスが重要となる XAML と WPF の一般的なシナリオも、いくつか存在します。 たとえば、特定のアニメーションとストーリーボードのサポート クラスでは Name プロパティがサポートされていませんが、多くの場合、アニメーションを制御するためにコード内でこれらのクラスを参照する必要があります。 後でコードから参照する場合は、XAML で作成されたタイムラインおよび変換の属性として x:Name を指定する必要があります。

クラスのプロパティとして Name を使用できる場合、Name と x:Name は属性として同義に使用できますが、両方が同じ要素に指定されていると、解析の例外が発生します。 XAML がマークアップ コンパイルされている場合は、マークアップ コンパイル時に例外が発生します。それ以外の場合は、読み込み時に発生します。

Name は、XAML 属性構文を使用して、および SetValue を使用してコードで設定できます。ただし、コードで Name プロパティを設定しても、XAML が既に読み込まれているほとんどの状況で、XAML 名前スコープ内で代表的なフィールド参照が作成されるわけではありません。 コードで Name を設定するのではなく、適切な名前スコープに対してコードから NameScope メソッドを使用します。

また、Name は、プロパティ要素構文を内部テキストと共に使用して設定することもできますが、これは一般的ではありません。 これに対し、x:Name は XAML プロパティ要素構文で、または SetValue を使用してコードで設定することはできません。これはディレクティブであるため、オブジェクトで属性構文を使用してのみ設定できます。

Silverlight の使用上の注意

Silverlight 用の x:Name に関しては、別途ドキュメントが用意されています。 詳細については、XAML 名前空間 (x:) 言語機能 (Silverlight) に関するページを参照してください。

関連項目