Attributo x:Name

Identifica in modo univoco gli elementi oggetto per l'accesso all'oggetto di cui è stata creata un'istanza da code-behind o codice generale. Una volta applicato a un modello di programmazione di supporto, x:Name può essere considerato equivalente alla variabile che contiene un riferimento a un oggetto, come restituito da un costruttore.

Utilizzo attributo XAML

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

Valori XAML

Grammatica XamlName

Di seguito è riportata la grammatica normativa per una stringa usata come chiave in questa implementazione XAML:

XamlName ::= NameStartChar (NameChar)*
NameStartChar ::= LetterCharacter | '_'
NameChar ::= NameStartChar | DecimalDigit
LetterCharacter ::= ('a'-'z') | ('A'-'Z')
DecimalDigit ::= '0'-'9'
CombiningCharacter::= none

• I caratteri sono limitati all'intervallo ASCII inferiore e, in particolare, alle lettere maiuscole e minuscole dell'alfabeto romano, alle cifre e al carattere di sottolineatura (_).
• L'intervallo di caratteri Unicode non è supportato.
• Un nome non può iniziare con una cifra. Alcune implementazioni di strumenti antepongono un trattino di sottolineatura (_) a una stringa se l'utente fornisce una cifra come carattere iniziale o lo strumento genera automaticamente valori x:Name in base ad altri valori che contengono cifre.

Osservazioni:

L'elemento x:Name specificato diventa il nome di un campo creato nel codice sottostante al momento dell'elaborazione di XAML e tale campo contiene un riferimento all'oggetto. Il processo di creazione di questo campo è eseguito dai passaggi di destinazione di MSBuild, che sono anche responsabili dell'unione delle classi parziali per un file XAML e del relativo code-behind. Questo comportamento non è necessariamente specifico del linguaggio XAML. Si tratta dell'implementazione particolare applicata dalla programmazione UWP (Universal Windows Platform) per XAML per l'uso di x:Name nei relativi modelli di programmazione e applicazione.

Ogni elemento x:Name definito deve essere univoco all'interno di un ambito dei nomi XAML. In genere, un ambito dei nomi XAML è definito a livello di elemento radice di una pagina caricata e contiene tutti gli elementi al di sotto di tale elemento in una singola pagina XAML. Gli ambiti dei nomi XAML aggiuntivi sono definiti da qualsiasi modello di controllo o modello di dati definito in tale pagina. In fase di esecuzione, viene creato un altro ambito dei nomi XAML per l'elemento radice della struttura ad albero di oggetti creata da un modello di controllo applicato e anche dalle strutture ad albero di oggetti create da una chiamata a XamlReader.Load. Per ulteriori informazioni, vedere Ambiti dei nomi XAML.

Gli strumenti di progettazione spesso generano automaticamente valori x:Name per gli elementi quando vengono introdotti nell'area di progettazione. Lo schema di generazione automatica varia a seconda della finestra di progettazione in uso, ma uno schema tipico prevede la generazione di una stringa che inizia con il nome della classe che supporta l'elemento, seguito da un numero intero in sequenza crescente. Ad esempio, se si introduce il primo elemento Button nella finestra di progettazione, si potrebbe notare che in XAML tale elemento ha "Button1" come valore dell'attributo x:Name.

Non è possibile impostare x:Name nella sintassi degli elementi proprietà di XAML né nel codice usando SetValue. È possibile impostare x:Name solo usando la sintassi degli attributi XAML sugli elementi.

Note Specificamente per le app C++/CX, per l'elemento radice di una pagina di un file XAML non viene creato un campo sottostante per un riferimento x:Name. Se è necessario fare riferimento all'oggetto radice da code-behind C++, usare altre API o l'attraversamento albero. Ad esempio, è possibile chiamare FindName per un elemento figlio denominato e quindi chiamare Parent.

x:Name e altre proprietà Name

Anche alcuni tipi usati in XAML UWP hanno una proprietà denominata Name. Ad esempio, FrameworkElement.Name e TextElement.Name.

Se Name è disponibile come proprietà impostabile in un elemento, è possibile usare Name e x:Name in modo intercambiabile in XAML, ma si verifica un errore se si specificano entrambi gli attributi nello stesso elemento. Vi sono anche casi in cui è presente una proprietà Name ma è di sola lettura (come VisualState.Name). In questo caso, si usa sempre x:Name per denominare tale elemento in XAML, l'elemento Name di sola lettura è presente in scenari di codice meno comuni.

NotaIn genere non si dovrebbe usare FrameworkElement.Name come un modo per modificare valori originariamente impostati da x:Name, sebbene alcuni scenari facciano eccezione a questa regola generale. Negli scenari tipici, la creazione e la definizione di ambiti dei nomi XAML è un'operazione del processore XAML. La modifica di FrameworkElement.Name in fase di esecuzione può causare un allineamento non coerente della denominazione dei campi dell'ambito dei nomi/privati di XAML, di cui è difficile tenere traccia in code-behind.

x:Name e x:Key

È possibile applicare x:Name come attributo agli elementi in un ResourceDictionary affinché funga da sostituito dell'attributo x:Key (una regola prevede che tutti gli elementi in un ResourceDictionary devono avere un attributo x:Key o x:Name). Ciò è comune per le animazioni con storyboard. Per ulteriori informazioni, vedere la sezione ResourceDictionary e riferimenti a risorse XAML.