x:Name 指示詞x:Name Directive

在 XAML 名稱範圍中唯一識別 XAML 定義的元素。Uniquely identifies XAML-defined elements in a XAML namescope. 當架構提供 Api 或實行為,以便在執行時間存取 XAML 建立的物件圖形時,XAML 名稱範圍及其唯一性模型可以套用至具現化的物件。XAML namescopes and their uniqueness models can be applied to the instantiated objects, when frameworks provide APIs or implement behaviors that access the XAML-created object graph at run time.

XAML Attribute UsageXAML Attribute Usage

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

XAML 值XAML Values

XAMLNameValue 符合 XamlName 文法限制的字串。A string that conforms to the restrictions of the XamlName Grammar.

備註Remarks

套用 x:Name 至架構的支援程式設計模型之後,該名稱就相當於保存函式所傳回之物件參考或實例的變數。After x:Name is applied to a framework's backing programming model, the name is equivalent to the variable that holds an object reference or an instance as returned by a constructor.

指示詞使用的值在 x:Name XAML 名稱範圍內必須是唯一的。The value of an x:Name directive usage must be unique within a XAML namescope. 依預設,.NET XAML 服務 API 使用時,主要 XAML 名稱範圍是在單一 XAML 生產的 XAML 根項目上定義,並包含該 XAML 生產中包含的元素。By default when used by .NET XAML Services API, the primary XAML namescope is defined at the XAML root element of a single XAML production, and encompasses the elements that are contained in that XAML production. 可能會在單一 XAML 生產環境中發生的其他離散 XAML 名稱範圍,可由架構定義以處理特定案例。Additional discrete XAML namescopes that might occur within a single XAML production can be defined by frameworks to address specific scenarios. 例如,在 WPF 中,新的 XAML 名稱範圍是由也在該 XAML 生產環境中定義的任何範本所定義和建立。For example, in WPF, new XAML namescopes are defined and created by any template that is also defined on that XAML production. 如需 XAML 名稱範圍 (針對 WPF 撰寫的詳細資訊,但) 的許多 XAML 名稱範圍概念相關的詳細資訊,請參閱 WPF XAML 名稱範圍For more information about XAML namescopes (written for WPF but relevant for many XAML namescope concepts), see WPF XAML Namescopes.

一般情況下, x:Name 不應該在也使用的情況下套用 x:KeyIn general, x:Name should not be applied in situations that also use x:Key. 特定現有架構的 XAML 執行已在和之間引進替代概念 x:Key x:Name ,但這並不是建議的作法。XAML implementations by specific existing frameworks have introduced substitution concepts between x:Key and x:Name, but that is not a recommended practice. .NET XAML 服務在處理名稱/金鑰資訊(例如或)時,不支援這類替代概念 INameScope DictionaryKeyPropertyAttribute.NET XAML Services does not support such substitution concepts when handling name/key information such as INameScope or DictionaryKeyPropertyAttribute.

Permittance 和 x:Name 名稱唯一性強制的規則,可能會由特定的執行架構定義。Rules for permittance of x:Name as well as the name uniqueness enforcement are potentially defined by specific implementing frameworks. 不過,若要與 .NET XAML 服務搭配使用,XAML 名稱範圍唯一性的架構定義應該與 INameScope 本檔中的資訊定義一致,而且應該使用與該資訊套用所在的相同規則。However, to be usable with .NET XAML Services, the framework definitions of XAML namescope uniqueness should be consistent with the definition of INameScope information in this documentation, and should use the same rules regarding where the information is applied. 例如,執行會將 Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) 各種標記專案分成不同的 NameScope 範圍,例如資源字典、頁面層級 XAML 所建立的邏輯樹狀結構、範本和其他延後的內容,然後在這些 xaml 名稱範圍內強制執行 xaml 名稱唯一性。For example, the Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) implementation divides various markup elements into separate NameScope ranges, such as resource dictionaries, the logical tree created by the page-level XAML, templates, and other deferred content, and then enforces XAML name uniqueness within each of those XAML namescopes.

針對使用 .NET XAML 服務 XAML 物件寫入器的自訂類型, x:Name 可建立或變更對應至類型的屬性。For custom types that use .NET XAML Services XAML object writers, a property that maps to x:Name on a type can be established or changed. 您可以 RuntimeNamePropertyAttribute 在類型定義程式碼中參考要對應之屬性的名稱,以定義此行為。You define this behavior by referencing the name of the property to map with the RuntimeNamePropertyAttribute in the type definition code. RuntimeNamePropertyAttribute 是類型層級的屬性。RuntimeNamePropertyAttribute is a type-level attribute.

Using.NET XAML 服務可讓您藉由執行介面,以架構中立的方式定義 XAML 名稱範圍支援的支援邏輯 INameScopeUsing.NET XAML Services, the backing logic for XAML namescope support can be defined in a framework-neutral way by implementing the INameScope interface.

WPF 使用注意事項WPF Usage Notes

WPFWPF 使用 XAML、部分類別和程式碼後端之應用程式的標準組建設定下, x:Name 當標記編譯組建工作處理時,指定的會成為基礎程式碼中所建立之欄位的名稱 XAMLXAML ,而該欄位會保存物件的參考。Under the standard build configuration for a WPFWPF application that uses XAML, partial classes, and code-behind, the specified x:Name becomes the name of a field that is created in the underlying code when XAMLXAML is processed by a markup compilation build task, and that field holds a reference to the object. 依預設,建立的欄位為內部。By default, the created field is internal. 您可以藉由指定 x:FieldModifier 屬性來變更欄位存取權。You can change field access by specifying the x:FieldModifier attribute. 在 WPF 和 Silverlight 中,此順序是標記編譯定義並命名部分類別中的欄位,但值一開始是空的。In WPF and Silverlight, the sequence is that the markup compile defines and names the field in a partial class, but the value is initially empty. 然後, InitializeComponent 會從類別的函式中呼叫名為的產生方法。Then, a generated method named InitializeComponent is called from within the class constructor. InitializeComponent 包含 FindName 使用 x:Name 部分類別之 XAML 定義部分中的每個值做為輸入字串的呼叫。InitializeComponent consists of FindName calls using each of the x:Name values that exist in the XAML-defined part of the partial class as input strings. 傳回值接著會指派給 like 命名欄位參考,以使用從 XAML 剖析建立的物件填滿域值。The return values are then assigned to the like-named field reference to fill the field values with objects that were created from XAML parsing. 執行 InitializeComponent 可讓您直接使用/功能變數名稱參考執行時間物件圖形 x:Name ,而不 FindName 需要在您需要 XAML 定義物件的參考時明確呼叫。The execution of InitializeComponent make it possible to reference the run time object graph using the x:Name / field name directly, rather than having to call FindName explicitly any time you need a reference to a XAML-defined object.

若是使用 Microsoft Visual Basic 目標的 WPF 應用程式,並包含具有組建動作的 XAML 檔案 Page ,則在編譯期間會建立個別的參考屬性,將關鍵字加入至 WithEvents 所有具有的元素 x:Name ,以支援 Handles 事件處理常式委派的語法。For a WPF application that uses the Microsoft Visual Basic targets and includes XAML files with Page build action, a separate reference property is created during compilation that adds the WithEvents keyword to all elements that have an x:Name, to support Handles syntax for event handler delegates. 此屬性一律為 public。This property is always public. 如需詳細資訊,請參閱 Visual Basic 和 WPF 事件處理For more information, see Visual Basic and WPF Event Handling.

x:Name WPF XAML 處理器會使用,在載入時間將名稱註冊到 XAML 名稱範圍中,即使頁面不是由組建動作進行標記編譯 (例如,資源字典的鬆散 XAML) 。x:Name is used by the WPF XAML processor to register a name into a XAML namescope at load time, even for cases where the page is not markup-compiled by build actions (for example, loose XAML of a resource dictionary). 這種行為的原因之一,是因為系結 x:Name 可能需要這樣做 ElementNameOne reason for this behavior is because the x:Name is potentially needed for ElementName binding. 如需詳細資料,請參閱資料系結 總覽For details, see Data Binding Overview.

如先前所述, x:Name Name 在同時使用的情況下, (或) 不應套用 x:KeyAs mentioned previously, x:Name (or Name) should not be applied in situations that also use x:Key. WPFWPF ResourceDictionary 具有將本身定義為 XAML 名稱範圍的特殊行為,但會傳回未實作為或 null 值給 api,以 INameScope 強制執行這種行為。The WPFWPF ResourceDictionary has a special behavior of defining itself as a XAML namescope but returning Not Implemented or null values for INameScope APIs as a way to enforce this behavior. 如果 WPF XAML 剖析器遇到 Namex:Name 在 xaml 定義中 ResourceDictionary ,則名稱不會加入至任何 xaml 名稱範圍。If the WPF XAML parser encounters Name or x:Name in a XAML-defined ResourceDictionary, the name is not added to any XAML namescope. 嘗試從任何 XAML 名稱範圍和方法找出該名稱 FindName 將不會傳回有效的結果。Attempting to find that name from any XAML namescope and the FindName methods will not return valid results.

X:Name 和名稱x:Name and Name

許多 WPF 應用程式案例都可以避免使用此 x:Name 屬性,因為許多 Name 重要基類的預設 XAML 命名空間中所指定的相依性屬性(例如 FrameworkElement ,和)都會 FrameworkContentElement 滿足相同的目的。Many WPF application scenarios can avoid any use of the x:Name attribute, because the Name dependency property as specified in the default XAML namespace for several of the important base classes such as FrameworkElement and FrameworkContentElement satisfies this same purpose. 仍有一些常見的 XAML 和 WPF 案例,也就是在架構層級沒有屬性之專案的程式碼存取權 Name 是很重要的。There are still some common XAML and WPF scenarios where code access to an element with no Name property at the framework level is important. 例如,某些動畫和分鏡腳本支援類別不支援 Name 屬性,但通常需要在程式碼中參考,才能控制動畫。For example, certain animation and storyboard support classes do not support a Name property, but they often need to be referenced in code in order to control the animation. x:Name如果您想要稍後在程式碼中參考它們,您應該在以 XAML 建立的時間軸和轉換上,指定做為屬性。You should specify x:Name as an attribute on timelines and transforms that are created in XAML, if you intend to reference them from code later.

如果 Name 可當做類別上的屬性 Name 來使用,而且 x:Name 可以當做屬性交換使用,但如果兩個專案都指定在相同的專案上,則會產生 parse 例外狀況。If Name is available as a property on the class, Name and x:Name can be used interchangeably as attributes, but a parse exception will result if both are specified on the same element. 如果 XAML 是標記編譯的,則例外狀況會發生在標記編譯中,否則會發生在載入時。If the XAML is markup compiled, the exception will occur on the markup compile, otherwise it occurs on load.

Name 您可以使用 XAML 屬性語法來設定,並在程式碼中使用, SetValue 但請注意,在程式碼中設定 Name 屬性不會在已載入 xaml 的大部分情況下,于 xaml 名稱範圍內建立代表欄位參考。Name can be set using XAML attribute syntax, and in code using SetValue; note however that setting the Name property in code does not create the representative field reference within the XAML namescope in most circumstances where the XAML is already loaded. 請不要嘗試在程式 Name 代碼中設定,而是使用程式 NameScope 代碼中的方法,針對適當的名稱範圍。Instead of attempting to set Name in code, use NameScope methods from code, against the appropriate namescope.

Name 也可以使用具有內部文字的屬性元素語法來設定,但這種情況並不常見。Name can also be set using property element syntax with inner text, but that is uncommon. 相反地, x:Name 無法使用 XAML 屬性專案語法或在程式碼中設定, SetValue 它只能使用物件的屬性語法來設定,因為它是指示詞。In contrast, x:Name cannot be set in XAML property element syntax, or in code using SetValue; it can only be set using attribute syntax on objects because it is a directive.

Silverlight 使用注意事項Silverlight Usage Notes

x:Name Silverlight 會另外記載。x:Name for Silverlight is documented separately. 如需詳細資訊,請參閱 XAML 命名空間 (x: ) 語言功能 (Silverlight) For more information, see XAML Namespace (x:) Language Features (Silverlight).

另請參閱See also