Direttiva x:Name

Articolo
10/18/2023

Identifica in modo univoco gli elementi definiti da XAML in un ambito dei nomi XAML. Gli ambiti dei nomi XAML e i relativi modelli di univocità possono essere applicati agli oggetti di cui è stata creata un'istanza, quando i framework forniscono API o implementano comportamenti che accedono al grafico oggetti creato da XAML in fase di esecuzione.

Uso della sintassi XAML per gli attributi

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

Valori XAML

Valore	Descrizione
`XAMLNameValue`	Stringa conforme alle restrizioni della grammatica XamlName.

Osservazioni

Dopo x:Name l'applicazione al modello di programmazione di backup di un framework, il nome equivale alla variabile che contiene un riferimento a un oggetto o un'istanza restituita da un costruttore.

Il valore di un utilizzo di direttiva x:Name deve essere univoco all'interno di un ambito dei nomi XAML. Per impostazione predefinita, se usata dall'API dei servizi XAML .NET, l'ambito dei nomi XAML primario viene definito nell'elemento radice XAML di una singola produzione XAML e include gli elementi contenuti in tale produzione XAML. Altri ambiti dei nomi XAML discreti che possono verificarsi all'interno di una singola produzione XAML possono essere definiti dai framework per gestire scenari specifici. Ad esempio, in WPF i nuovi ambiti dei nomi XAML vengono definiti e creati da qualsiasi modello definito anche nell'ambiente di produzione XAML. Per altre informazioni sugli ambiti dei nomi XAML (scritti per WPF, ma pertinenti per molti concetti relativi all'ambito dei nomi XAML), vedi Ambiti dei nomi XAML WPF.

In generale, x:Name non deve essere applicato in situazioni che usano x:Keyanche . Le implementazioni XAML in base a framework esistenti specifici hanno introdotto concetti di sostituzione tra x:Key e x:Name, ma questa non è una procedura consigliata. I servizi XAML .NET non supportano tali concetti di sostituzione quando si gestiscono informazioni relative a nome/chiave, INameScope ad esempio o DictionaryKeyPropertyAttribute.

Le regole per l'autorizzazione e x:Name l'imposizione dell'univocità dei nomi sono potenzialmente definite da framework di implementazione specifici. Tuttavia, per essere utilizzabile con i servizi XAML .NET, le definizioni del framework dell'univocità dell'ambito dei nomi XAML devono essere coerenti con la definizione delle INameScope informazioni in questa documentazione e devono usare le stesse regole relative alla posizione in cui vengono applicate le informazioni. Ad esempio, l'implementazione di Windows Presentation Foundation (WPF) divide vari elementi di markup in intervalli separati NameScope , ad esempio i dizionari risorse, l'albero logico creato dal codice XAML a livello di pagina, i modelli e altri contenuti posticipati e quindi applica l'univocità del nome XAML all'interno di ognuno di questi ambiti dei nomi XAML.

Per i tipi personalizzati che usano writer di oggetti XAML di servizi XAML .NET, è possibile stabilire o modificare una proprietà mappata a x:Name su un tipo. Questo comportamento viene definito facendo riferimento al nome della proprietà di cui eseguire il mapping con RuntimeNamePropertyAttribute nel codice di definizione del tipo. RuntimeNamePropertyAttribute è un attributo a livello di tipo.

Using.NET servizi XAML, la logica di backup per il supporto dell'ambito dei nomi XAML può essere definita in modo indipendente dal framework implementando l'interfaccia INameScope .

Note sull'utilizzo di WPF

Nella configurazione di compilazione standard per un'applicazione WPF che usa XAML, classi parziali e code-behind, l'oggetto specificato x:Name diventa il nome di un campo creato nel codice sottostante quando XAML viene elaborato da un'attività di compilazione di 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 è che la compilazione del markup definisce e assegna un nome al campo in una classe parziale, ma il valore è inizialmente vuoto. Viene quindi chiamato un metodo generato denominato InitializeComponent dall'interno del costruttore della classe. InitializeComponent è costituito da FindName chiamate che usano ognuno dei x:Name valori presenti nella parte definita da XAML della classe parziale come stringhe di input. I valori restituiti vengono quindi assegnati al riferimento di campo simile al nome per riempire i valori dei campi con gli oggetti creati dall'analisi XAML. L'esecuzione di consente di fare riferimento direttamente all'oggetto grafico dell'ora di InitializeComponent esecuzione usando il x:Name /nome del campo, invece di dover chiamare FindName in modo esplicito ogni volta che è necessario un riferimento a un oggetto definito da XAML.

Per un'applicazione WPF che usa le destinazioni di Microsoft Visual Basic e include file XAML con Page azione di compilazione, durante la compilazione viene creata una proprietà di riferimento separata che aggiunge la WithEvents parola chiave a tutti gli elementi con un x:Nameoggetto , per supportare Handles la sintassi per i delegati del gestore eventi. Questa proprietà è sempre pubblica. Per altre informazioni, vedere Visual Basic e la gestione degli eventi WPF.

x:Name viene usato dal processore XAML WPF per registrare un nome in un ambito dei nomi XAML in fase di caricamento, anche nei casi in cui la pagina non viene compilata tramite markup dalle azioni di compilazione (ad esempio, XAML libero di un dizionario risorse). Un motivo per questo comportamento è dovuto al fatto che l'oggetto è potenzialmente necessario per ElementName l'associazionex:Name. Per informazioni dettagliate, vedere Panoramica del data binding.

Come indicato in precedenza, x:Name (o Name) non deve essere applicato in situazioni che usano x:Keyanche . WPF ResourceDictionary ha un comportamento speciale di definirsi come ambito dei nomi XAML, ma restituendo valori Non implementati o Null per INameScope le API come modo per applicare questo comportamento. Se il parser XAML WPF rileva Name o x:Name in un oggetto xaml definito ResourceDictionary, il nome non viene aggiunto ad alcun ambito dei nomi XAML. Il tentativo di trovare tale nome da qualsiasi ambito dei nomi XAML e i FindName metodi non restituiranno risultati validi.

x:Name e Name

Molti scenari di applicazione WPF possono evitare qualsiasi uso dell'attributo x:Name , perché la Name proprietà di dipendenza come specificato nello spazio dei nomi XAML predefinito per diverse classi di base importanti, ad esempio FrameworkElement e FrameworkContentElement soddisfa lo stesso scopo. Esistono ancora alcuni scenari XAML e WPF comuni in cui l'accesso al codice a un elemento senza Name proprietà a livello di framework è importante. Ad esempio, alcune classi di animazione e storyboard supportano classi che non supportano una Name proprietà, ma spesso devono essere referenziate nel codice per controllare l'animazione. Devi specificare x:Name come attributo nelle sequenze temporali e nelle trasformazioni create in XAML, se intendi farvi riferimento dal codice in un secondo momento.

Se Name è disponibile come proprietà nella classe Name e x:Name può essere usata in modo intercambiabile come attributi, ma un'eccezione di analisi genererà se entrambi vengono specificati nello stesso elemento. Se il markup XAML viene compilato, l'eccezione si verificherà nella compilazione del markup; in caso contrario, si verifica al caricamento.

Name può essere impostato usando la sintassi degli attributi XAML e nel codice usando SetValue; tieni presente che l'impostazione della Name proprietà nel codice non crea il riferimento di campo rappresentativo all'interno dell'ambito dei nomi XAML nella maggior parte dei casi in cui xaml è già caricato. Invece di tentare di impostare Name nel codice, usare NameScope i metodi del codice rispetto all'ambito dei nomi appropriato.

Name può anche essere impostato usando la sintassi degli elementi di proprietà con il testo interno, ma questo non è comune. Al contrario, x:Name non può essere impostato nella sintassi degli elementi di proprietà XAML o nel codice usando SetValue; può essere impostato solo usando la sintassi degli attributi per gli oggetti perché è una direttiva.

Note sull'utilizzo di Silverlight

x:Name per Silverlight è documentato separatamente. Per altre informazioni, vedere Funzionalità del linguaggio dello spazio dei nomi XAML (x:) (Silverlight).