x:Key ディレクティブx:Key Directive

XAML で定義されたディクショナリで作成および参照される要素を一意に識別します。Uniquely identifies elements that are created and referenced in a XAML-defined dictionary. x:Key 値を XAML オブジェクトに追加するのは、リソース ディクショナリ (ResourceDictionary など) のリソースを識別するための最も一般的な方法です。Adding an x:Key value to a XAML object element is the most common way to identify a resource in a resource dictionary, for example in a WPF ResourceDictionary.

XAML 属性の使用方法XAML Attribute Usage

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

XAML 属性の使用方法 (WPF 固有)XAML Attribute Usage (WPF-specific)

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

XAML 値XAML Values

stringKeyValue キーとして使用するテキスト文字列。A text string to use as a key. テキスト文字列に準拠する必要があります、 XamlName の文法します。The text string must conform to the XamlName Grammar.
markupExtensionUsage マークアップ拡張機能の区切り記号内{}、マークアップ拡張機能の使用をキーとして使用するオブジェクトを提供します。Within the markup extension delimiters {}, a markup extension usage that provides an object to use as a key. 「解説」を参照してください。See Remarks.

RemarksRemarks

x:Key は XAML のリソース ディクショナリの概念をサポートしています。x:Key supports the XAML resource dictionary concept. 言語としての XAML ではリソース ディクショナリの実装は定義されていません。特定の UI フレーム ワークによって定義されています。XAML as a language doesn't define a resource dictionary implementation, that is left to specific UI frameworks. WPF における XAML リソース ディクショナリを実装する方法の詳細については、次を参照してください。 XAML リソースします。To learn more about how XAML resource dictionaries are implemented in WPF, see XAML Resources.

XAML 2006 および WPF では、x:Key属性として指定する必要があります。In XAML 2006 and WPF, x:Key must be provided as an attribute. 文字列ではないキーも使用できますが、文字列ではない値を属性形式で提供するためには、マークアップ拡張機能を使用する必要があります。You can still use nonstring keys, but this requires a markup extension usage in order to provide the nonstring value in attribute form. XAML 2009 を使用している場合x:Key以外のオブジェクトの種類をキーとするディクショナリを明示的にサポートするために文字列の中間マークアップ拡張機能を必要とせずを要素として指定できます。If you are using XAML 2009, x:Key can be specified as an element, to explicitly support dictionaries keyed by object types other than strings without requiring a markup extension intermediate. このトピックの「XAML 2009」のセクションを参照してください。See the "XAML 2009" section in this topic. XAML 2006 の実装に具体的には、「解説」セクションの残りの部分が適用されます。The remainder of the Remarks section applies specifically to the XAML 2006 implementation.

属性値x:Key任意の文字列で定義できる、 XamlName の文法またはマークアップ拡張機能を使用して評価されたオブジェクトを指定できます。The attribute value of x:Key can be any string defined in the XamlName Grammar or can be an object evaluated through a markup extension. WPF の例については、「WPF の使用上の注意」を参照してください。See "WPF Usage Notes" for an example from WPF.

通常、IDictionary の実装である親要素の子要素には、そのディクショナリ内の一意のキー値を指定する x:Key 属性を含める必要があります。Child elements of a parent element that is an IDictionary implementation must typically include an x:Key attribute that specifies a unique key value within that dictionary. フレームワークでは、特定の型の x:Key を代用するために、エイリアス化されたキー プロパティを実装する場合があります。このようなプロパティを定義する型には、DictionaryKeyPropertyAttribute 属性を設定する必要があります。Frameworks might implement aliased key properties to substitute for x:Key on particular types; types that define such properties should be attributed with DictionaryKeyPropertyAttribute.

x:Key の指定に相当するコードは、基になる IDictionary で使用されるキーです。The code equivalent of specifying x:Key is the key that is used for the underlying IDictionary. たとえば、マークアップで適用される WPF のリソースの x:Key は、コードでリソースを WPF の key に追加する場合、ResourceDictionary.AddResourceDictionary パラメーターの値と同等です。For example, an x:Key that is applied in markup for a resource in WPF is equivalent to the value of the key parameter of ResourceDictionary.Add when you add the resource to a WPF ResourceDictionary in code.

WPF の使用上の注意WPF Usage Notes

通常、WPF の IDictionary などの ResourceDictionary の実装である親オブジェクトの子オブジェクトには、x:Key 属性を含める必要があります。また、キー値は、そのディクショナリ内で一意である必要があります。Child objects of a parent object that is an IDictionary implementation, such as the WPF ResourceDictionary, must typically include an x:Key attribute, and the key value must be unique within that dictionary. ただし、次のように 2 つの重要な例外があります。There are two notable exceptions:

  • 一部の WPF 型は、ディクショナリの使用に対して暗黙のキーを宣言します。Some WPF types declare an implicit key for dictionary usage. たとえば、Style が設定された TargetType や、DataTemplate が設定された DataType は、ResourceDictionary に格納して、暗黙のキーを使用できます。For example, a Style with a TargetType, or a DataTemplate with a DataType, can be in a ResourceDictionary and use the implicit key.

  • WPF は、マージされたリソース ディクショナリの概念をサポートしています。WPF supports a merged resource dictionary concept. キーは、マージされたディクショナリ間で共有できます。また、共有されたキーの動作には、FindResource を使用してアクセスできます。Keys can be shared between the merged dictionaries, and the shared key behavior can be accessed using FindResource. 詳細については、「Merged Resource Dictionaries」を参照してください。For more information, see Merged Resource Dictionaries.

通常、WPF XAML の実装およびアプリケーション モデルでは、キーの一意性が XAML マークアップ コンパイラによってチェックされることはありません。In the overall WPF XAML implementation and application model, key uniqueness is not checked by the XAML markup compiler. その代わり、x:Key 値が指定されていない場合や一意でない場合は、読み込み時に XAML パーサー エラーが発生します。Instead, missing or nonunique x:Key values cause load-time XAML parser errors. ただし、WPF のディクショナリの処理を Visual Studio できます多くの場合、このようなエラー、設計フェーズで。However, Visual Studio handling of dictionaries for WPF can often note such errors in the design phase.

ここに示す構文において、ResourceDictionary オブジェクトは WPF XAML プロセッサが Resources コレクションを取得するためのコレクションを生成する方法を暗黙的に決定することに注意してください。Note that in the syntax shown, the ResourceDictionary object is implicit in how the WPF XAML processor produces a collection to populate a Resources collection. ResourceDictionary は、通常はマークアップで要素として明示的に指定されませんが、わかりやすくするために必要に応じて明示的に指定することもできます (その場合、このオブジェクトは、Resources プロパティ要素とディクショナリに設定される項目間のコレクション オブジェクト要素になります)。A ResourceDictionary is not typically provided explicitly as an element in markup, although it can be in some cases if wanted for clarity (it would be a collection object element between the Resources property element and the items within that populate the dictionary). なぜコレクション オブジェクトがほぼ常に暗黙の要素にマークアップの詳細については、次を参照してください。 XAML 構文の詳細します。For information about why a collection object is almost always an implicit element in markup, see XAML Syntax In Detail.

WPF XAML 実装では、リソース ディクショナリ キーの処理は、ResourceKey 抽象クラスによって定義されます。In the WPF XAML implementation, the handling for resource dictionary keys is defined by the ResourceKey abstract class. ただし、WPF XAML プロセッサは、使用方法に基づいてキーごとに別の基になる拡張型を生成します。However the WPF XAML processor produces different underlying extension types for keys based on their usages. たとえば、DataTemplate または任意の派生クラスのキーは個別に処理され、異なる DataTemplateKey オブジェクトを生成します。For example, the key for a DataTemplate or any derived class is handled separately, and produces a distinct DataTemplateKey object.

基本的な XAML 定義では、キーと名前で異なるディレクティブと言語要素 (x:Keyx:Name) が使用されます。Keys and names use different directives and language elements (x:Key versus x:Name) in the basic XAML definition. また、キーと名前は、それらの概念の WPF 定義およびアプリケーションにより異なる状況において使用されます。Keys and names are also used in different situations by the WPF definition and application of these concepts. 詳細については、次を参照してください。 WPF XAML 名前スコープします。For details, see WPF XAML Namescopes.

既に説明したように、キー値はマークアップ拡張機能によって指定され、文字列値以外になる場合があります。As stated previously, the value of a key can be supplied through a markup extension and can be other than a string value. WPF シナリオの例は、の値を提供するx:Key可能性があります、 ComponentResourceKeyします。An example WPF scenario is that the value of x:Key may be a ComponentResourceKey. 特定のコントロールでは、スタイルを完全に置き換えることなく、そのコントロールの外観と動作の一部に影響を与えるカスタム スタイル リソースの型に対応するスタイル キーが公開されます。Certain controls expose a style key of that type for a custom style resource that influences part of the appearance and behavior of that control without totally replacing the style. このようなキーの例として、ButtonStyleKey が挙げられます。An example of such a key is ButtonStyleKey.

WPF のマージされたディクショナリ機能では、キーの一意性およびキーの検索動作について考慮を要する点があります。The WPF merged dictionary feature introduces additional considerations for key uniqueness and key lookup behavior. 詳細については、「Merged Resource Dictionaries」を参照してください。For more information, see Merged Resource Dictionaries.

XAML 2009XAML 2009

XAML 2009 は、制限を緩和するx:Key属性形式で常に提供されます。XAML 2009 relaxes the restriction that x:Key always be provided in attribute form.

WPF では、マークアップ コンパイルされていない XAML については、XAML 2009 の機能を使用することができます。In WPF, you can use XAML 2009 features, but only for XAML that is not markup-compiled. WPF 向けにマークアップ コンパイルされた XAML、および XAML の BAML 形式は、現在、XAML 2009 のキーワードと機能をサポートしていません。Markup-compiled XAML for WPF and the BAML form of XAML do not currently support the XAML 2009 keywords and features.

XAML 2009 で指定できますx:Key次の使用法を使用して要素。Under XAML 2009, you can specify x:Key elements through the following usage:

XAML 要素の使用 (XAML 2009 のみ)XAML Element Usage (XAML 2009 only)

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

XAML 値XAML Values

keyObject 専用のディクショナリで指定された object のキーとして使用されるオブジェクトの、オブジェクト要素。Object element for the object that is used as the key for a given object in a specialized dictionary.
  • この種類の使用方法のコンテナー/親は、ここには示しません。The container/parent for this kind of use is not shown here. object は、専用のディクショナリの実装を表すオブジェクト要素の子であると想定されます。object is expected to be a child of an object element that represents a specialized dictionary implementation. keyObject は、その専用のディクショナリの実装のキーとして適切なオブジェクト インスタンス (または値の型の値) であると想定されます。keyObject is expected to be an object instance (or a value of a value type) that is appropriate as the key for that particular specialized dictionary implementation.

  • WPF は、この使用方法を必要とするディクショナリを実装しません。WPF does not implement dictionaries that require this usage. オブジェクト キーは XAML 言語のより一般的な機能であり、カスタム ディクショナリのシナリオで XAML でのディクショナリ作成が望まれる場合に有益であることがあります。Object keys is more a general feature of the XAML language, possibly useful for certain custom dictionary scenarios where creating the dictionary in XAML is desirable. リソースに対して文字列以外のキーを使用する暗黙的なスタイルなどの WPF 機能については、別の方法によってキーを確立、または指定することができるので、オブジェクト キーを使用する必要はありません。For WPF features such as implicit styles that use non-string keys for resources, other techniques for establishing or specifying the keys exist, so using an object key is not necessary.

  • keyObject直接オブジェクト インスタンスではなく、オブジェクト要素の形式でマークアップ拡張機能の使用可能性があります。keyObject could also be a markup extension usage in object element form, rather than a direct object instance.

Silverlight の使用上の注意Silverlight Usage Notes

Silverlight 用の x:Key に関しては、別途ドキュメントが用意されています。x:Key for Silverlight is documented separately. 詳細については、次を参照してくださいXAML Namespace (x:)。言語機能 (Silverlight)します。For more information, see XAML Namespace (x:) Language Features (Silverlight).

関連項目See also