x:Name 屬性

發行項
04/22/2024

唯一識別物件元素，以便從程式碼後置或一般程式碼存取具現化物件。套用至支援程式設計模型之後，可以將 x:Name 視為與保留物件參考的變數相等，如建構函式所傳回。

XAML 屬性用法

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

XAML 值

詞彙	描述
XAMLNameValue	符合 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 命名範圍。

當元素引入設計介面時，設計工具通常會自動產生元素的 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 屬性

UWP XAML 中使用的某些類型也有名為 Name 的屬性。例如，FrameworkElement.Name 和 TextElement.Name。

如果 Name 可在元素上當做可設定的屬性使用，則 Name 和 x: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 資源參考一節。

共用方式為