共用方式為


x:Name 屬性

唯一識別物件元件,以便從後台程式碼或一般程式碼存取已實例化的物件。 套用至基礎程式設計模型之後,x:Name 可以被視為相當於建構函式所傳回的持有物件參考的變數。

XAML 屬性使用方式

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

XAML 值

術語 Description
XAML名稱值 符合 XamlName 文法限制的字串。

XamlName 文法

以下是 XAML 實作中用作索引鍵的字串規範文法:

XamlName ::= NameStartChar (NameChar)*
NameStartChar ::= LetterCharacter | '_'
NameChar ::= NameStartChar | DecimalDigit
LetterCharacter ::= ('a'-'z') | ('A'-'Z')
DecimalDigit ::= '0'-'9'
CombiningCharacter::= none
  • 字元僅限於較低的 ASCII 範圍,更具體地說是羅馬字母大寫和小寫字母、數字和底線 (_) 字元。
  • 不支援 Unicode 字元範圍。
  • 名稱不能以數字開頭。 如果使用者提供數字作為初始字元,或工具會根據包含數字的其他值自動產生 x:Name 值,則某些工具實作會在字串前面加上底線 (_)。

備註

指定的 x:Name 會成為處理 XAML 時在基礎程式碼中建立的欄位名稱,而該欄位會保留物件的參考。 建立此欄位的程式是由 MSBuild 目標步驟所執行,這些步驟也負責聯結 XAML 檔案及其程式碼後置的部分類別。 此行為不一定由 XAML 語言規範;這是 XAML 在通用 Windows 平台 (UWP) 程式設計和應用程式模型中特定的實作方式,允許使用 x:Name

每個定義的 x:Name 在 XAML 名稱範圍內都必須是唯一的。 一般而言,XAML 名稱範圍是在載入頁面的根元素層級定義,並包含單一 XAML 頁面中該元素下的所有元素。 其他 XAML 名稱範圍是由該頁面上定義的任何控制項範本或資料範本所定義。 在執行階段,會為由套用的控制項範本建立的物件樹狀結構的根目錄創建另一個 XAML 名稱範圍,並且由呼叫 XamlReader.Load 建立的物件樹狀結構也會創建一個 XAML 名稱範圍。 如需詳細資訊,請參閱 XAML 名稱範圍

設計工具通常會在元素引入設計介面時自動產生元素的 x:Name 值。 自動產生方案會因您所使用的設計器而有所不同,但一般方案是產生一個字串,該字串首先是用作元素後端的類別名稱,然後是逐步增加的整數。 例如,如果您將第一個 Button 元素引進設計工具,您可能會看到在 XAML 中,此元素的 x:Name 屬性值為 “Button1”。

x:Name 無法在 XAML 屬性元素語法中設定,或在使用 SetValue 的程式碼中設定。 x:Name 只能在元素上使用 XAML 屬性語法來設定。

備註

特別是針對 C++/CX 應用程式,XAML 檔案或頁面的根元素不會建立 x:Name 參考的後援欄位。 如果您需要從 C++ 背後代碼參考根物件,請使用其他的 API 或遍歷樹狀結構。 例如,您可以針對已知的具名子元素呼叫 FindName ,然後呼叫 Parent

x:Name 和其他 Name 屬性

XAML 中使用的某些類型也有名為 Name 的屬性。 例如, FrameworkElement.NameTextElement.Name

如果 Name 可作為元素上的可設定屬性使用,則 Namex:Name 可以在 XAML 中互換使用,但如果在相同的元素上指定這兩個屬性,則會導致錯誤。 在某些情況下,有 Name 屬性,但它是唯讀的 (例如 VisualState.Name)。 如果是這種情況,您通常會使用 x:Name 來命名 XAML 中的該元素,而唯讀的 Name 則是針對一些不太常見的程式碼情況而存在。

請注意 FrameworkElement.Name 通常不應該用作更改最初由 x:Name 設置的值的方法,儘管有些情況是該一般規則的例外情況。 在一般案例中,XAML 名稱範圍的建立和定義是 XAML 處理器作業。 在執行階段修改 FrameworkElement.Name 可能會導致 XAML 名稱範圍/私人欄位命名對齊方式不一致,這很難在程式碼後置中追蹤。

x:Name 和 x:Key

x:Name 可以作為屬性套用至 ResourceDictionary 內的元素,以取代 x:Key 屬性。 (這是 ResourceDictionary 中的所有元素都必須具有 x:Key 或 x:Name 屬性的規則。這對於 分鏡腳本動畫很常見。 如需詳細資訊,請參閱 ResourceDictionary 和 XAML 資源參考一節。