x:Key 屬性x:Key attribute

唯一識別建立和參照為資源的元素,存在 ResourceDictionary 中。Uniquely identifies elements that are created and referenced as resources, and which exist within a ResourceDictionary.

XAML 屬性用法XAML attribute usage

<ResourceDictionary>
  <object x:Key="stringKeyValue".../>
</ResourceDictionary>

XAML 屬性用法 (隱含 ResourceDictionary)XAML attribute usage (implicit ResourceDictionary)

<object.Resources>
  <object x:Key="stringKeyValue".../>
</object.Resources>

XAML 值XAML values

詞彙Term 描述Description
物件 (object)object 可共用的任何物件。Any object that is shareable. 請參閱 ResourceDictionary 與 XAML 資源參考See ResourceDictionary and XAML resource references.
stringKeyValuestringKeyValue 做為索引鍵的合法字串,必須符合 XamlName 文法。A true string used as a key, which must conform to the XamlName> grammar. 請參閱下面的<XamlName 文法>。See "XamlName grammar" below.  

XamlName 文法XamlName grammar

下列是字串的基準文法,該字串在通用 Windows 平台 (UWP) XAML 實作中被當做是一個索引鍵:The following is the normative grammar for a string that is used as a key in the Universal Windows Platform (UWP) XAML implementation:

XamlName ::= NameStartChar (NameChar)*
NameStartChar ::= LetterCharacter | '_'
NameChar ::= NameStartChar | DecimalDigit
LetterCharacter ::= ('a'-'z') | ('A'-'Z')
DecimalDigit ::= '0'-'9'
CombiningCharacter::= none
  • 字元會限制為較低的 ASCII 範圍,更明確地說,是以羅馬字母大寫和小寫字母、數位和底線 (_) 字元。Characters are restricted to the lower ASCII range, and more specifically to Roman alphabet uppercase and lowercase letters, digits, and the underscore (_) character.
  • 不支援 Unicode 字元範圍。The Unicode character range is not supported.
  • 名稱開頭不可以是數字。A name cannot begin with a digit.

備註Remarks

ResourceDictionary 的子元素通常包含 x:Key 屬性,該屬性會指定該字典內的唯一索引鍵值。Child elements of a ResourceDictionary generally include an x:Key attribute that specifies a unique key value within that dictionary. XAML 處理器在載入期間會強制執行索引鍵唯一性。Key uniqueness is enforced at load time by the XAML processor. 非唯一的 x:Key 值將導致 XAML 剖析例外狀況。Non-unique x:Key values will result in XAML parse exceptions. 如果是 {StaticResource} 標記延伸所要求,任何未解析的索引鍵也會導致 XAML 剖析例外狀況。If requested by {StaticResource} markup extension, a non-resolved key will also result in XAML parse exceptions.

x:Keyx:Name 並非相同的概念。x:Key and x:Name are not identical concepts. x:Key 專門用在資源字典中。x:Key is used exclusively in resource dictionaries. x:Name 則用於 XAML 的所有區域。x:Name is used for all areas of XAML. 使用索引鍵值的 FindName 呼叫將不會擷取索引資源。A FindName call using a key value will not retrieve a keyed resource. 資源字典中定義的物件可能會有 x:Keyx:Name 或是兩者。Objects defined in a resource dictionary may have an x:Key, an x:Name or both. 金鑰和名稱不需要符合。The key and name are not required to match.

請注意,在顯示的隱含語法中,ResourceDictionary 物件在 XAML 處理器如何產生新物件以填入 Resources 集合方面是隱含的。Note that in the implicit syntax shown, the ResourceDictionary object is implicit in how the XAML processor produces a new object to populate a Resources collection.

等同於指定 x:Key 的程式碼,是使用含有基礎 ResourceDictionary 的索引鍵的任何作業。The code equivalent of specifying x:Key is any operation that uses a key with the underlying ResourceDictionary. 例如,當您新增資源到 ResourceDictionary 時,在資源的標記中套用的 x:Key 等同於 Insertkey 參數值。For example, an x:Key applied in markup for a resource is equivalent to the value of the key parameter of Insert when you add the resource to a ResourceDictionary.

如果資源字典中的項目為目標的 StyleControlTemplate,則可以忽略 x:Key 的值;不管是哪一種情況,資源項目的隱含索引鍵都是會解譯為字串的 TargetType 值。An item in a resource dictionary can omit a value for x:Key if it is a targeted Style or ControlTemplate; in each of these cases the implicit key of the resource item is the TargetType value interpreted as a string. 如需詳細資訊,請參閱快速入門:設定控制項的樣式ResourceDictionary 與 XAML 資源參考For more info, see Quickstart: styling controls and ResourceDictionary and XAML resource references.