FrameworkElement.Name Proprietà

  • Riferimento

Definizione

Spazio dei nomi:
Microsoft.UI.Xaml
Modifica

Ottiene o imposta il nome di identificazione dell'oggetto. Quando un processore XAML crea l'albero degli oggetti dal markup XAML, il codice di runtime può fare riferimento all'oggetto dichiarato XAML da questo nome.

public:
 property Platform::String ^ Name { Platform::String ^ get(); void set(Platform::String ^ value); };
winrt::hstring Name();

void Name(winrt::hstring value);
public string Name { get; set; }
var string = frameworkElement.name;
frameworkElement.name = string;
Public Property Name As String
<frameworkElement Name="xamlNameString"/>

Valore della proprietà

String

Platform::String

winrt::hstring

Nome dell'oggetto, che deve essere una stringa valida nella grammatica XamlName (vedere la tabella in riferimento all'attributo x:Name ). Il valore predefinito è una stringa vuota.

Esempio

In questo esempio viene ottenuto un valore per Name da un oggetto esistente e viene usato tale nome per ritargete un'animazione. Si destinazione un'animazione impostando la proprietà associata Storyboard.TargetName .

private void Start_Animation(object sender, PointerRoutedEventArgs e)
{

    // If the Storyboard is running and you try to change
    // properties of its animation objects programmatically, 
    // an error will occur.
    myStoryboard.Stop();

    // Get a reference to the rectangle that was clicked.
    Rectangle myRect = (Rectangle)sender;

    // Change the TargetName of the animation to the name of the
    // rectangle that was clicked.
    myDoubleAnimation.SetValue(Storyboard.TargetNameProperty, myRect.Name);

    // Begin the animation.
    myStoryboard.Begin();
}

Commenti

L'utilizzo più comune di questa proprietà consiste nel specificare l'attributo x:Name per un oggetto nel markup XAML o per leggere tale valore come impostato nel markup. Nella maggior parte dei modi, l'attributo e la x:NameName proprietà sono equivalenti. In qualsiasi singolo elemento, l'attributo e la x:NameName proprietà si escludono a vicenda come attributi XAML. Se si tenta di impostare entrambi x:Name e Name sullo stesso elemento oggetto nel markup, viene generato un errore del parser.

Quando si usano le azioni di compilazione pagina predefinite per XAML, qualsiasi elemento XAML con un attributo x:Name o Name genera riferimenti al campo che vengono eventualmente popolati da InitializeComponent quando viene caricato XAML. I riferimenti al campo abilitano un modello di programmazione in cui gli oggetti possono essere direttamente a cui fare riferimento per nome nel code-behind specifico della pagina, dopo che l'albero degli oggetti XAML viene caricato in una pagina o in un'app.

I nomi devono essere univoci in un nome XAML. In genere, il nomescope XAML è definito dalla pagina XAML, ma alcune funzionalità, ad esempio modelli o chiamate all'API, ad esempio XamlReader.Load , possono definire nomi XAML separati. Per altre info, vedi Ambiti dei nomi XAML.

Name non deve mai essere localizzato. Name viene usato come variabile nome campo nel code-behind. Questo codice è in genere inaccessibile al localizzatore che potrebbe altrimenti avere accesso ai file XAML che definiscono l'interfaccia utente, anche se ciò dipende dal modello di distribuzione e dalle procedure di localizzazione. Questo è un motivo per cui non è consigliabile visualizzare le stringhe provenienti da Name nell'interfaccia utente dell'app.

Scenari per nome

Impostazione x:Name o Name in XAML che definisce gli elementi dell'interfaccia utente supporta diversi scenari principali:

  • Destinazione animazione Per applicare un'animazione a una proprietà dell'oggetto, è necessario indirizzare un'istanza specifica. A tale scopo, impostando la proprietà associata Storyboard.TargetName in qualsiasi sequenza temporale. Il valore impostato qui è la stringa assegnata come x:Name oggetto o Name. Per altre info, vedi Animazioni con storyboard.
  • Parti di un modello di controllo Per supportare il modello di stato visivo e l'inizializzazione del controllo, gli autori del controllo devono specificare Name i valori per le parti chiave di un controllo modello. Per altre informazioni, vedere Modelli di controllo XAML.
  • Interazione generale del tempo di esecuzione Ad esempio, il codice all'interno di un gestore eventi potrebbe gestire un evento in un oggetto che fornisce l'interfaccia utente della modifica, ma la modifica alle proprietà si verifica in un altro elemento dell'interfaccia utente vicina. Il modo più semplice per scrivere codice per questa situazione consiste nell'usare il riferimento al campo generato da un Nameoggetto .

FindName

Il metodo di utilità FindName, disponibile in qualsiasi FrameworkElement, può trovare oggetti in base al nome nell'albero degli oggetti, purché si trovino nel nome XAML corrente. FindName esegue ricerche nell'intero albero degli oggetti creato da XAML. Tecnicamente, ciò che FindName sta effettivamente cercando è il nome XAML, che non mantiene la metafora dell'albero ed è invece rappresentato come tabella hash dei nomi. FindName non è possibile trovare nomi definiti nei modelli applicati. Per trovare elementi nei modelli applicati, usare VisualTreeHelper.GetChild per ottenere l'oggetto radice del modello applicato. È quindi possibile chiamare FindName su tale oggetto radice e si eseguirà una ricerca nel nome XAML del modello anziché nella pagina maggiore.

Nome e data binding

Non è possibile usare il valore stringa di Name come valore di origine diretta per un'origine data binding. Se è necessario visualizzare lo stesso valore stringa dell'interfaccia Name utente con l'associazione, è necessario replicare lo stesso valore nella proprietà Tag , che può essere usato come origine di associazione delle proprietà. Non usare Name anche come destinazione di associazione.

Il valore di o Name è l'identificatore usato per identificare l'elemento di x:Name origine per un'associazione ElementName. Per altre informazioni, vedere Data binding in profondità.

Impostazione del nome nel codice

È possibile impostare il valore di per un oggetto in fase di Name esecuzione, ma sono presenti alcune considerazioni e limitazioni importanti da tenere presente.

La modifica del valore di nel codice in fase di Name esecuzione se l'oggetto ha un valore precedente Name impostato in XAML non è in genere consigliato. Questo perché l'impostazione di un nome dopo il caricamento dell'albero degli oggetti non creerà o modifica il nome di identificazione del riferimento al campo equivalente. Se esiste già un riferimento al campo perché x:Name viene fornito nel markup iniziale e si modifica il valore di Name, il campo e il nome che è necessario utilizzare per trovare l'oggetto tramite FindName sono ora diversi perché il campo rimane come nome definito dal markup.

L'impostazione di un valore per un Name oggetto creato nel codice e quindi non ha mai un valore nome definito da XAML è appropriato per determinati scenari. Uno di questi scenari è se si vuole essere in grado di trovare oggetti creati da XAML o creati dal codice nell'albero usando FindName come funzione di utilità comune. Per rendere lo scenario funzionante, l'Windows Runtime continua a usare e aggiungere alla rappresentazione hashtable del nome XAML in fase di esecuzione. Se si sta tentando di aggiungere nuovi oggetti denominati a un albero di oggetti creato in gran parte XAML esistente, i nomi devono essere univoci, altrimenti si verifica un'eccezione di nome duplicata. L'eccezione del nome duplicato potrebbe non verificarsi nel tentativo di impostare Name. Fino a quando non si tenta di aggiungere l'oggetto duplicato all'albero dell'oggetto principale, il nuovo oggetto ha un proprio nome XAML autonomo. È solo al momento in cui si connette l'oggetto a un albero di oggetti più grande che è possibile rilevare la condizione del nome duplicato. In alternativa, l'eccezione potrebbe verificarsi sull'operazione che gli oggetti connessi nell'albero, ad esempio in una chiamata al metodo di una raccolta che si connette all'albero Add degli oggetti principale.

Può essere difficile conoscere i valori name già esistenti nel nome XAML a cui si aggiungerà successivamente il nuovo oggetto. Non esiste un'API specifica che segnala la tabella hash completa dei nomi esistenti in un nome XAML. Se si impostano i valori name nel codice in modo esteso, potrebbe essere necessaria una tecnica per generare stringhe di nome univoche per l'utilizzo del tempo di esecuzione oppure è necessario eseguire il wrapping delle chiamate che aggiungono nuovi oggetti denominati in un blocco try-catch per rilevare le eccezioni che potrebbero risultare da un nome duplicato. In alternativa, è possibile aggiungere codice personalizzato all'implementazione InitializeComponent che legge i valori dei nomi generati da XAML.

Si noti che è possibile impostare Name solo in fase di esecuzione per gli oggetti che sono un FrameworkElement o un Oggetto Inline. Se un oggetto non dispone di una proprietà e l'impostazione del nome in XAML richiederebbe l'uso x:Name dell'attributo anziché Name, non è disponibile alcuna Name API di runtime per l'impostazione del nome di runtime di tale oggetto.

Si applica a

Vedi anche