Direttiva x:Name
Identifica in modo univoco gli elementi XAML nell'ambito dei nomi XAML. I namescope XAML e i rispettivi modelli di univocità possono essere applicati agli oggetti di cui è stata creata un'istanza, quando i framework forniscono API o implementano i comportamenti che accedono all'oggetto grafico creato da XAML in fase di esecuzione.
Utilizzo della sintassi XAML per gli attributi
<object x:Name="XAMLNameValue".../>
Valori XAML
XAMLNameValue |
Stringa conforme alle limitazioni dell'oggetto Grammatica XamlName. |
Note
Una volta applicato x:Name a un modello di programmazione di supporto del framework, il nome è uguale alla variabile che contiene un riferimento a un oggetto o un'istanza come restituito da un costruttore.
Il valore di un utilizzo della direttiva x:Name deve essere univoco all'interno di un ambito dei nomi XAML. Per impostazione predefinita, quando viene utilizzata dall'API dei servizi XAML di .NET Framework, i principali namescope XAML sono definiti nell'elemento radice XAML di una singola produzione di XAML e includono gli elementi contenuti nella produzione di XAML. Altri namescope XAML discreti che potrebbero verificarsi all'interno di una singola produzione XAML possono essere definiti dai framework per indirizzare scenari specifici. Ad esempio, in WPF, i nuovi ambiti dei nomi XAML vengono definiti e creati da un modello definito nella produzione XAML. Per ulteriori informazioni sui NameScope di XAML (scritti per WPF ma attinenti per molti concetti di NameScope di XAML), vedere NameScope XAML WPF.
In generale, x:Name non deve essere applicata in situazioni che utilizzano anche x:Key. Le implementazioni XAML da framework specifici esistenti hanno introdotto i concetti di sostituzione tra x:Key e x:Name, ma non si tratta di una procedura consigliata. I servizi XAML di .NET Framework non supportano tali concetti di sostituzione in caso di gestione di informazioni di tipo nome/chiave come INameScope o DictionaryKeyPropertyAttribute.
Le regole dell'autorizzazione di x:Name e dell'imposizione di univocità del nome sono definite potenzialmente dai framework di implementazione specifici. Tuttavia, per essere utilizzabili con i Servizi XAML di .NET Framework, le definizioni di framework dell'univocità dell'ambito dei nomi XAML devono essere coerenti con la definizione delle informazioni INameScope in questa documentazione e devono utilizzare le stesse regole relative al contesto in cui sono applicate le informazioni. Ad esempio, l'implementazione Windows Presentation Foundation (WPF) divide vari elementi di markup in intervalli NameScope separati, come ad esempio dizionari risorse, l'albero logico creato da XAML a livello di pagina, modelli e altri contenuti posticipati, e successivamente attiva l'univocità del nome XAML in ciascun spazio dei nomi XAML.
Per tipi personalizzati che utilizzano i writer degli oggetti XAML dei servizi XAML di .NET Framework, una proprietà che esegue il mapping a x:Name su un tipo può essere stabilita o può essere modificata. È possibile definire questo comportamento facendo riferimento al nome della proprietà per eseguire il mapping con RuntimeNamePropertyAttribute nel codice della definizione del tipo. RuntimeNamePropertyAttribute è un attributo a livello di tipo.
Utilizzando i servizi Using.NET Framework XAML, la logica di supporto per il supporto di NameScope di XAML può essere definito in modo framework-neutro implementando l'interfaccia INameScope.
Note sull'utilizzo di WPF
Con la configurazione di compilazione standard per un progetto di applicazione WPF che utilizza XAML, classi parziali e code-behind, l'oggetto x:Name specificato diviene il nome di un campo creato nel codice sottostante quando XAML viene elaborato da un'attività di compilazione con markup e tale campo contiene un riferimento all'oggetto. Per impostazione predefinita, il campo creato è interno. È possibile modificare l'accesso al campo specificando l'attributo x:FieldModifier. In WPF e Silverlight, la sequenza è impostata in modo che la compilazione del markup definisce e nomina il campo in una classe parziale, ma il valore è inizialmente vuoto. Quindi, un metodo generato denominato InitializeComponent viene chiamato dall'interno del costruttore della classe. InitializeComponent è costituito dalle chiamate a FindName utilizzando ognuno dei valori x:Name che si trovano nella parte definita in XAML della classe parziale come stringhe di input. I valori restituiti vengono quindi assegnati al riferimento di campo omonimo in modo da riempire i valori di campo con oggetti creati dall'analisi XAML. L'esecuzione di InitializeComponent consente di fare riferimento direttamente all'oggetto grafico in fase di esecuzione mediante x:Name/nome campo, anziché dovendo chiamare FindName in modo esplicito quando si necessita di un riferimento a un oggetto definito in XAML.
In caso di un'applicazione WPF che utilizza le destinazioni di Microsoft Visual Basic e include i file XAML con un'azione di compilazione Page viene creata una proprietà di riferimento separata durante la compilazione, che aggiunge la parola chiave WithEvents a tutti gli elementi che dispongono di un attributo x:Name, per supportare la sintassi Handles per i delegati del gestore eventi. Questa proprietà è sempre pubblica. Per ulteriori informazioni, vedere Visual Basic and WPF Event Handling.
x:Name viene utilizzato dal processore XAML WPF per registrare un nome in un namescope XAML al momento del carico, persino nei casi in cui la pagina non viene compilata in markup da azioni di compilazione (ad esempio, quando XAML è separato da un dizionario della risorsa). Questo comportamento si verifica perché l'attributo x:Name può essere necessario per l'associazione ElementName. Per informazioni dettagliate, vedere Data Binding Overview.
Come menzionato precedentemente, x:Name (o Name) non devono essere applicati in situazioni che utilizzano anche x:Key. WPF ResourceDictionary segue un comportamento speciale, autodefinendosi come namescope XAML ma restituendo Not Implemented o valori null per le API INameScope in maniera tale da imporre il comportamento stesso. Se il parser XAML WPF rileva Name o x:Name in ResourceDictionarydefinito in XAML, il nome non viene aggiunto ad alcun namescope XAML. Se si tenta di trovare tale nome dai namescope XAML e i metodi FindName non vengono restituiti risultati validi.
Nome e x:Name
Diversi scenari di applicazioni WPF possono non utilizzare l'attributo x:Name perché la proprietà di dipendenza Name specificata all'interno dello spazio dei nomi XAML per molte delle classi base importanti, come ad esempio FrameworkElement e FrameworkContentElement soddisfa questo stesso scopo. Esistono ancora alcuni scenari XAML e WPF comuni in cui l'accesso di codice a un elemento senza alcuna proprietà Name a livello di framework è importante. Ad esempio, determinate classi di supporto di animazioni e storyboard non supportano una proprietà Name, ma è necessario farvi riferimento nel codice per comandare l'animazione. È necessario specificare x:Name come attributo nelle sequenze temporali e nelle trasformazioni create in XAML, se si intende utilizzarle come riferimento dal codice.
Se l'oggetto Name è disponibile come proprietà nella classe, gli oggetti Name e x:Name possono essere utilizzati in modo intercambiabile come attributi, tuttavia, un'eccezione di analisi risulterà se entrambi vengono specificati nello stesso elemento. Se nel XAML è stata eseguita la compilazione di markup, si verificherà l'eccezione sulla compilazione di markup, in caso contrario si verificherà nel caricamento.
Name può essere impostato utilizzando la sintassi per gli attributi XAML, e nel codice mediante SetValue; notare, tuttavia, che in alcune circostanze l'impostazione della proprietà Name nel codice non crea il riferimento rappresentativo del campo all'interno del namescope dove XAML è già caricato. Anziché tentare di impostare Name nel codice, utilizzare i metodi NameScope dal codice sul namescope corretto.
È possibile inoltre impostare Name utilizzando la sintassi per gli elementi delle proprietà con testo interno, ma è una procedura non comune. Al contrario, x:Name non può essere impostato nella sintassi dell'elemento della proprietà XAML o nel codice usando SetValue; tale impostazione può essere effettuata solo utilizzando la sintassi per gli attributi sugli oggetti perché è una direttiva.
Note sull'utilizzo di Silverlight.
x:Name per Silverlight è documentato separatamente. Per ulteriori informazioni, vedere Funzionalità del linguaggio dello spazio dei nomi XAML (x:).