Direttiva x:Name

Articolo
12/17/2024

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.

Utilizzo degli attributi XAML

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

Valori XAML

Valore	Descrizione
`XAMLNameValue`	Stringa conforme alle restrizioni del XamlName Grammar.

Osservazioni

Dopo che x:Name viene applicato al modello di programmazione di backup di un framework, il nome equivale alla variabile che contiene un riferimento all'oggetto o a 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 anche x:Key. Le implementazioni XAML in base a framework specifici esistenti hanno introdotto concetti di sostituzione tra x:Key e x:Name, ma non è una procedura consigliata. I servizi XAML .NET non supportano questi concetti di sostituzione quando si gestiscono informazioni relative a nome/chiave, ad esempio INameScope o DictionaryKeyPropertyAttribute.

Le regole per l'autorizzazione di x:Name e 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'ambito dei nomi XAML devono essere coerenti con la definizione delle informazioni INameScope 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 di NameScope separati, 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 in 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 in un tipo. Questo comportamento viene definito facendo riferimento al nome della proprietà per eseguire il mapping con il 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, il x:Name specificato 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 chiamate FindName usando ognuno dei valori x:Name 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 InitializeComponent consente di fare riferimento direttamente all'oggetto grafico dell'ora di esecuzione usando direttamente il nome di x:Name/campo, anziché 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, viene creata una proprietà di riferimento separata durante la compilazione che aggiunge la parola chiave WithEvents a tutti gli elementi con un x:Name, per supportare la sintassi Handles per i delegati del gestore eventi. Questa proprietà è sempre pubblica. Per altre informazioni, vedere Gestione degli eventi di Visual Basic e 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 il x:Name è potenzialmente necessario per ElementName binding. Per informazioni dettagliate, vedere panoramica del data binding .

Come indicato in precedenza, x:Name (o Name) non deve essere applicato in situazioni che usano anche x:Key. Il ResourceDictionary WPF ha un comportamento speciale di definirsi come ambito dei nomi XAML, ma restituendo valori Non implementati o Null per le API INameScope come modo per applicare questo comportamento. Se il parser XAML WPF rileva Name o x:Name in un ResourceDictionarydefinito da XAML, 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 metodi FindName non restituiranno risultati validi.

x:Name e Name

Molti scenari di applicazione WPF possono evitare qualsiasi uso dell'attributo x:Name, perché la proprietà di dipendenza Name 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 proprietà Name a livello di framework è importante. Ad esempio, alcune classi di animazione e storyboard supportano non supportano una proprietà Name, ma spesso devono essere referenziate nel codice per controllare l'animazione. Devi specificare x:Name come attributo per le sequenze temporali e le trasformazioni create in XAML, se vuoi farvi riferimento dal codice in un secondo momento.

Se Name è disponibile come proprietà nella classe , Name e x:Name possono essere usati in modo intercambiabile come attributi, ma un'eccezione di analisi genererà se entrambi sono 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; Si noti tuttavia che l'impostazione della proprietà Name nel codice non crea il riferimento al campo rappresentativo all'interno dell'ambito dei nomi XAML nella maggior parte dei casi in cui xaml è già caricato. Anziché tentare di impostare Name nel codice, usare i metodi NameScope dal 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 impostata 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 spazio dei nomi XAML (x:) Language Features (Silverlight).

Condividi tramite