FrameworkElement.Name Proprietà

  • Riferimento

Definizione

Spazio dei nomi:
Windows.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

Questo esempio ottiene un valore per Name da un oggetto esistente e usa 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();
}

Private Sub Start_Animation(ByVal sender As Object, ByVal e As PointerRoutedEventArgs)
    ' 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.
    Dim myRect As Rectangle = CType(sender, Rectangle)
    ' 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()
End Sub

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 x:Name e la proprietà Name sono equivalenti. In qualsiasi singolo elemento, l'attributo x:Name e la proprietà Name si escludono a vicenda come attributi XAML; se si tenta di impostare sia x:Name che Name nello 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 il codice 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.

Il nome non deve mai essere localizzato. Il nome viene usato come variabile di 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 di 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 destinazione di 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 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 i valori Name per le parti chiave di un controllo modello. Per altre informazioni, vedere Guida introduttiva: Modelli di controllo.
  • 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 nome.

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 la ricerca 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 e viene invece rappresentato come tabella hash dei nomi. FindName non riesce a trovare i 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 in 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 di Name nell'interfaccia utente con l'associazione, è necessario replicare lo stesso valore nella proprietà Tag , che può essere usato come origine di associazione delle proprietà. Non usare anche Nome come destinazione di associazione.

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

Impostazione del nome nel codice

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

La modifica del valore di Name nel codice in fase di esecuzione se l'oggetto ha un valore Name precedente 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 un riferimento al campo esiste già perché x:Name viene fornito nel markup iniziale e si modifica il valore di Name, il campo e il nome che è necessario usare per trovare l'oggetto tramite FindName sono ora diversi perché il campo rimane come nome definito dal markup.

L'impostazione di un valore Name per un oggetto creato nel codice e quindi non ha mai avuto 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 Nome. 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 ha connesso oggetti nell'albero, ad esempio in una chiamata al metodo Add di una raccolta che si connette all'albero 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 il proprio codice all'implementazione InitializeComponent che legge i valori dei nomi generati da XAML.

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

Si applica a

Vedi anche