x:Name 指示詞

發行項
10/18/2023

可唯一識別 XAML 命名範圍中 XAML 定義的元素。當架構提供 API 或實作在執行時間存取 XAML 建立的物件圖形時，XAML 命名範圍及其唯一性模型可以套用至具現化物件。

XAML Attribute Usage

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

XAML 值

值	Description
`XAMLNameValue`	符合 XamlName 文法限制的字串。

備註

套用至架構支援程式設計模型之後 x:Name ，名稱就相當於保留建構函式所傳回之物件參考或實例的變數。

指示詞用法的值 x:Name 在 XAML 命名範圍內必須是唯一的。根據預設，.NET XAML 服務 API 使用時，主要 XAML 名稱範圍定義于單一 XAML 生產環境的 XAML 根項目，並包含該 XAML 生產中包含的專案。在單一 XAML 生產環境中可能發生的其他離散 XAML 命名範圍可由架構定義，以解決特定案例。例如，在 WPF 中，新的 XAML 命名範圍是由任何同時在該 XAML 生產環境上定義的範本所定義和建立。如需 XAML 命名範圍的詳細資訊（針對 WPF 撰寫，但與許多 XAML 命名範圍概念有關），請參閱 WPF XAML 命名範圍。

一般而言， x:Name 在也使用 x:Key 的情況下，不應該套用。特定現有架構的 XAML 實作在和 x:Name 之間 x:Key 引進了替代概念，但這不是建議的做法。處理名稱/索引鍵資訊，例如 INameScope 或 DictionaryKeyPropertyAttribute 時，.NET XAML 服務不支援這類替代概念。

允許 x:Name 的規則以及名稱唯一性強制執行的規則可能是由特定實作架構所定義。不過，若要與 .NET XAML 服務搭配使用，XAML 名稱範圍唯一性的架構定義應該與本檔中的資訊定義 INameScope 一致，而且應該使用相同的規則來套用資訊。例如，Windows Presentation Foundation （WPF）實作會將各種標記元素分割成不同的 NameScope 範圍，例如資源字典、頁面層級 XAML、範本和其他延遲內容所建立的邏輯樹狀結構，然後在每個 XAML 命名範圍中強制執行 XAML 名稱唯一性。

對於使用 .NET XAML 服務 XAML 物件寫入器的自訂類型，可以建立或變更對應至 x:Name 類型的屬性。您可以藉由參考屬性的名稱來定義此行為，以便與 RuntimeNamePropertyAttribute 型別定義程式碼中的對應。 RuntimeNamePropertyAttribute 是類型層級屬性。

Using.NET XAML 服務，XAML 命名範圍支援的支援邏輯可藉由實 INameScope 作介面，以架構中性的方式定義。

WPF 使用方式注意事項

在使用 XAML、部分類別和程式碼後置之 WPF 應用程式的標準建置組態下，指定的 x:Name 會成為當 XAML 由標記編譯建置工作處理 XAML 時，在基礎程式碼中建立的功能變數名稱，且該欄位會保存物件的參考。根據預設，建立的欄位是內部欄位。您可以指定 x：FieldModifier 屬性來變更欄位存取。在 WPF 和 Silverlight 中，序列是標記編譯會定義並命名部分類別中的欄位，但值一開始是空的。然後，從類別建構函式內呼叫名為 InitializeComponent 的產生方法。 InitializeComponent 會 FindName 使用 x:Name XAML 定義部分類別中每個值做為輸入字串的呼叫所組成。傳回值接著會指派給類似命名的欄位參考，以使用從 XAML 剖析建立的物件填入域值。的執行 InitializeComponent 可讓您直接使用 x:Name / 功能變數名稱來參考執行時間物件圖形，而不需要在每次需要 XAML 定義物件的參考時明確呼叫 FindName 。

對於使用 Microsoft Visual Basic 目標的 WPF 應用程式，並包含具有 Page 建置動作的 XAML 檔案，編譯期間會建立個別的參考屬性，以將關鍵字新增 WithEvents 至具有 x:Name 的所有元素，以支援 Handles 事件處理常式委派的語法。此屬性一律為公用。如需詳細資訊，請參閱 Visual Basic 和 WPF 事件處理。

x:Name WPF XAML 處理器會在載入時將名稱註冊到 XAML 命名範圍，即使頁面不是透過建置動作編譯標記的情況（例如資源字典的鬆散 XAML）。此行為的原因之一，是因為 x:Name 可能需要系 ElementName 結。如需詳細資訊，請參閱資料系結概觀。

如先前所述， x:Name 在也使用 x:Key 的情況下，不應該套用（或 Name ）。 WPF ResourceDictionary 有一種特殊行為，其行為是將本身定義為 XAML 命名範圍，但會傳回 API 的「未實作 INameScope 」或 Null 值，做為強制執行此行為的方式。如果 WPF XAML 剖析器在 XAML 定義 ResourceDictionary 中遇到 Name 或 x:Name ，則名稱不會新增至任何 XAML 命名範圍。嘗試從任何 XAML 名稱範圍尋找該名稱，且 FindName 方法不會傳回有效的結果。

x：Name and Name

許多 WPF 應用程式案例都可以避免使用 x:Name 屬性，因為 Name 相依性屬性如數個重要基類的預設 XAML 命名空間中所指定，例如 FrameworkElement 並 FrameworkContentElement 滿足此相同用途。仍有一些常見的 XAML 和 WPF 案例，其中程式碼存取架構層級沒有 Name 屬性的專案很重要。例如，某些動畫和分鏡腳本支援類別不支援 Name 屬性，但它們通常需要以程式碼參考，才能控制動畫。如果您想要稍後從程式碼參考它們，您應該在時間軸和 XAML 中建立的轉換上指定 x:Name 為屬性。

如果 Name 可以當做類別上的屬性使用， Name 而且 x:Name 可以交替使用作為屬性，但如果兩者都指定在相同的專案上，就會產生剖析例外狀況。如果 XAML 已編譯標記，則會在標記編譯時發生例外狀況，否則會在載入時發生。

Name 您可以使用 XAML 屬性語法設定，並在程式 SetValue 代碼中使用來設定 ;請注意，在程式碼中設定 Name 屬性並不會在 XAML 命名範圍中建立代表性的欄位參考，在大部分情況下，XAML 已經載入。不要嘗試在程式碼中設定 Name ，而是針對適當的命名範圍使用 NameScope 來自程式碼的方法。

Name 也可以使用屬性專案語法搭配內部文字來設定，但這種情況並不常見。相反地， x:Name 不能在 XAML 屬性元素語法中設定，或是使用 SetValue 的程式碼中，它只能使用物件的屬性語法來設定，因為它是指示詞。

Silverlight 使用量注意事項

x:Name 針對 Silverlight 會個別記載。如需詳細資訊，請參閱 XAML 命名空間（x：）語言功能（Silverlight）。

共用方式為