x:Key ディレクティブ

  • [アーティクル]

XAML で定義されたディクショナリで作成および参照される要素を一意に識別します。 x:Key 値を XAML オブジェクトに追加するのは、リソース ディクショナリ (ResourceDictionary など) のリソースを識別するための最も一般的な方法です。

XAML 属性の使用方法

<object x:Key="stringKeyValue".../>  
-or-  
<object x:Key="{markupExtensionUsage}".../>

XAML 属性の使用方法 (WPF 固有)

<object.Resources>  
  <object x:Key="stringKeyValue".../>  
</object.Resources>  
-or-  
<object.Resources>  
  <object x:Key="{markupExtensionUsage}".../>  
</object.Resources>

XAML 値

値 [説明]
stringKeyValue キーとして使用するテキスト文字列。 テキスト文字列は、XamlName 文法に準拠している必要があります。
markupExtensionUsage マークアップ拡張機能の区切り記号 {} 内では、キーとして使用するオブジェクトを提供するマークアップ拡張機能の使用方法です。 「解説」を参照してください。

Remarks

x:Key は XAML のリソース ディクショナリの概念をサポートしています。 言語としての XAML ではリソース ディクショナリの実装は定義されていません。特定の UI フレーム ワークによって定義されています。 WPF での XAML リソース ディクショナリの実装方法の詳細については、「XAML リソースの概要 (WPF .NET)」を参照してください。

XAML 2006 および WPF では、x:Key は属性として指定する必要があります。 文字列ではないキーも使用できますが、文字列ではない値を属性形式で提供するためには、マークアップ拡張機能を使用する必要があります。 XAML 2009 を使用する場合は、x:Key を要素として指定し、マークアップ拡張機能の仲介を必要とすることなく、文字列以外のオブジェクトの種類をキーとするディクショナリを明示的にサポートすることができます。 このトピックの「XAML 2009」のセクションを参照してください。 解説セクションの残りの部分では、XAML 2006 の実装について説明します。

x:Key の属性値には、XamlName 文法で定義されている任意の文字列またはマークアップ拡張機能を使用して評価されるオブジェクトを指定できます。 WPF の例については、「WPF の使用上の注意」を参照してください。

通常、IDictionary の実装である親要素の子要素には、そのディクショナリ内の一意のキー値を指定する x:Key 属性を含める必要があります。 フレームワークでは、特定の型の x:Key を代用するために、エイリアス化されたキー プロパティを実装する場合があります。このようなプロパティを定義する型には、DictionaryKeyPropertyAttribute 属性を設定する必要があります。

x:Key の指定に相当するコードは、基になる IDictionary で使用されるキーです。 たとえば、マークアップで適用される WPF のリソースの x:Key は、コードでリソースを WPF の key に追加する場合、ResourceDictionary.Add の ResourceDictionary パラメーターの値と同等です。

WPF の使用上の注意

通常、WPF の IDictionary などの ResourceDictionary の実装である親オブジェクトの子オブジェクトには、x:Key 属性を含める必要があります。また、キー値は、そのディクショナリ内で一意である必要があります。 ただし、次のように 2 つの重要な例外があります。

  • 一部の WPF 型は、ディクショナリの使用に対して暗黙のキーを宣言します。 たとえば、TargetType が設定された Style や、DataType が設定された DataTemplate は、ResourceDictionary に格納して、暗黙のキーを使用できます。

  • WPF は、マージされたリソース ディクショナリの概念をサポートしています。 キーは、マージされたディクショナリ間で共有できます。また、共有されたキーの動作には、FindResource を使用してアクセスできます。 詳細については、「マージされたリソース ディクショナリ」を参照してください。

通常、WPF XAML の実装およびアプリケーション モデルでは、キーの一意性が XAML マークアップ コンパイラによってチェックされることはありません。 その代わり、x:Key 値が指定されていない場合や一意でない場合は、読み込み時に XAML パーサー エラーが発生します。 ただし、Visual Studio での WPF のディクショナリの処理では、このようなエラーの多くは、設計フェーズで指摘されます。

ここに示す構文において、ResourceDictionary オブジェクトは WPF XAML プロセッサが Resources コレクションを取得するためのコレクションを生成する方法を暗黙的に決定することに注意してください。 ResourceDictionary は、通常はマークアップで要素として明示的に指定されませんが、わかりやすくするために必要に応じて明示的に指定することもできます (その場合、このオブジェクトは、Resources プロパティ要素とディクショナリに設定される項目間のコレクション オブジェクト要素になります)。 コレクション オブジェクトがマークアップでほぼ必ず暗黙の要素になる理由の詳細については、「XAML 構文の詳細」を参照してください。

WPF XAML 実装では、リソース ディクショナリ キーの処理は、ResourceKey 抽象クラスによって定義されます。 ただし、WPF XAML プロセッサは、使用方法に基づいてキーごとに別の基になる拡張型を生成します。 たとえば、DataTemplate または任意の派生クラスのキーは個別に処理され、異なる DataTemplateKey オブジェクトを生成します。

基本的な XAML 定義では、キーと名前で異なるディレクティブと言語要素 (x:Key と x:Name) が使用されます。 また、キーと名前は、それらの概念の WPF 定義およびアプリケーションにより異なる状況において使用されます。 詳細については、「WPF XAML 名前空間」を参照してください。

既に説明したように、キー値はマークアップ拡張機能によって指定され、文字列値以外になる場合があります。 WPF シナリオの例として、x:Key の値が ComponentResourceKey になる場合が挙げられます。 特定のコントロールでは、スタイルを完全に置き換えることなく、そのコントロールの外観と動作の一部に影響を与えるカスタム スタイル リソースの型に対応するスタイル キーが公開されます。 このようなキーの例として、ButtonStyleKey が挙げられます。

WPF のマージされたディクショナリ機能では、キーの一意性およびキーの検索動作について考慮を要する点があります。 詳細については、「マージされたリソース ディクショナリ」を参照してください。

XAML 2009

XAML 2009 では、x:Key を常に属性形式で提供するという制限が緩和されています。

WPF では XAML 2009 の機能を使用できますが、マークアップのコンパイルが行われない XAML に限定されます。 WPF 向けにマークアップ コンパイルされた XAML、および XAML の BAML 形式は、現在、XAML 2009 のキーワードと機能をサポートしていません。

XAML 2009 では、次の使用方法で x:Key 要素を指定できます。

XAML 要素の使用 (XAML 2009 のみ)

<object>  
  <x:Key>  
keyObject  
  </x:Key>  
...  
</object>

XAML 値

値 [説明]
keyObject 専用のディクショナリで指定された object のキーとして使用されるオブジェクトの、オブジェクト要素。

  • この種類の使用方法のコンテナー/親は、ここには示しません。 object は、専用のディクショナリの実装を表すオブジェクト要素の子であると想定されます。 keyObject は、その専用のディクショナリの実装のキーとして適切なオブジェクト インスタンス (または値の型の値) であると想定されます。

  • WPF は、この使用方法を必要とするディクショナリを実装しません。 オブジェクト キーは XAML 言語のより一般的な機能であり、カスタム ディクショナリのシナリオで XAML でのディクショナリ作成が望まれる場合に有益であることがあります。 リソースに対して文字列以外のキーを使用する暗黙的なスタイルなどの WPF 機能については、別の方法によってキーを確立、または指定することができるので、オブジェクト キーを使用する必要はありません。

  • keyObject は、直接オブジェクト インスタンスではなく、オブジェクト要素の形式で、マークアップ拡張機能の使用法になる場合もあります。

Silverlight の使用上の注意

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

関連項目