FrameworkElement.Name Eigenschaft

  • Referenz

Definition

Namespace:
Windows.UI.Xaml
Bearbeiten

Ruft den identifizierenden Namen des Objekts ab oder legt diesen fest. Wenn ein XAML-Prozessor die Objektstruktur aus XAML-Markup erstellt, kann Laufzeitcode mit diesem Namen auf das XAML-deklarierte Objekt verweisen.

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"/>

Eigenschaftswert

String

Platform::String

winrt::hstring

Der Name des -Objekts, bei dem es sich um eine Zeichenfolge handeln muss, die in der XamlName-Grammatik gültig ist (siehe Tabelle in x:Name-Attributreferenz ). Der Standardwert ist eine leere Zeichenfolge.

Beispiele

In diesem Beispiel wird ein Wert für Name aus einem vorhandenen Objekt abgerufen und dieser Name verwendet, um eine Animation neu zu erstellen. Sie richten eine Animation als Ziel ein, indem Sie die angefügte Storyboard.TargetName-Eigenschaft festlegen.

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

Hinweise

Die häufigste Verwendung dieser Eigenschaft besteht darin, das x:Name-Attribut für ein Objekt im XAML-Markup anzugeben oder diesen Wert so zu lesen, wie er im Markup festgelegt wurde. In den meisten Arten sind das x:Name-Attribut und die Name-Eigenschaft gleichwertig. Bei jedem einzelnen Element schließen sich das x:Name-Attribut und die Name-Eigenschaft gegenseitig als XAML-Attribute aus. Wenn Sie versuchen, sowohl x:Name als auch Name für dasselbe Objektelement im Markup festzulegen, wird ein Parserfehler ausgelöst.

Wenn Sie die Standardaktionen zum Erstellen von Seiten für XAML verwenden, generiert jedes XAML-Element mit einem x:Name-Attribut oder Name Feldverweise, die schließlich von InitializeComponent aufgefüllt werden, wenn das XAML geladen wird. Die Feldverweise ermöglichen ein Programmiermodell, bei dem Objekte direkt per Namen in Ihrem seitenspezifischen CodeBehind referenziert werden können, sobald die XAML-Objektstruktur in eine Seite oder App geladen wurde.

Namen müssen in einem XAML-Namescope eindeutig sein. Im Allgemeinen wird das XAML-Namescope durch die XAML-Seite definiert, aber bestimmte Features wie Vorlagen oder API-Aufrufe wie XamlReader.Load können separate XAML-Namescopes definieren. Weitere Informationen finden Sie unter XAML-Namescopes.

Name sollte nie lokalisiert werden. Name wird als Feldnamenvariable in CodeBehind verwendet. Auf solchen Code kann in der Regel der Lokalisierer nicht zugreifen, der andernfalls zugriff auf XAML-Dateien hat, die die Benutzeroberfläche definieren. Dies hängt jedoch vom Bereitstellungsmodell und den Lokalisierungsverfahren ab. Dies ist ein Grund, warum Sie keine Zeichenfolgen anzeigen sollten, die von Name in Ihrer App-Benutzeroberfläche stammen.

Szenarien für Name

Das Festlegen von x:Name oder Name in der XAML, die UI-Elemente definiert, unterstützt mehrere Hauptszenarien: + Animationsziel Um eine Animation auf eine Objekteigenschaft anzuwenden, müssen Sie eine bestimmte instance als Ziel festlegen. Dazu legen Sie die angefügte Storyboard.TargetName-Eigenschaft auf einer beliebigen Zeitachse fest. Der Wert, den Sie hier festlegen, ist die Zeichenfolge, die Sie als x:Name oder Name zugewiesen haben. Weitere Informationen finden Sie unter Storyboardanimationen.

  • Teile einer Steuerelementvorlage Um das visuelle Zustandsmodell und die Steuerelementinitialisierung zu unterstützen, sollten Steuerelementautoren Name-Werte für die wichtigsten Teile eines vorlagenbasierten Steuerelements angeben. Weitere Informationen finden Sie unter Schnellstart: Steuerelementvorlagen.
  • Allgemeine Laufzeitinteraktion Code in einem Ereignishandler kann z. B. ein Ereignis für ein Objekt behandeln, das die Änderungsbenutzeroberfläche bereitstellt, aber die Änderung der Eigenschaften erfolgt für ein anderes in der Nähe befindliches UI-Element. Die einfachste Möglichkeit, Code für diese Situation zu schreiben, besteht darin, den aus einem Namen generierten Feldverweis zu verwenden.

FindName

Die Hilfsprogrammmethode FindName, die in jedem FrameworkElement verfügbar ist, kann Objekte nach Namen in der Objektstruktur suchen, solange sie sich im aktuellen XAML-Namescope befinden. FindName durchsucht die XAML-erstellte Objektstruktur vollständig. Technisch gesehen sucht FindName tatsächlich das XAML-Namescope, das die Strukturmetapher nicht behält und stattdessen als Hashtabelle mit Namen dargestellt wird. FindName kann keine Namen finden, die in angewendeten Vorlagen definiert sind. Um Elemente in angewendeten Vorlagen zu finden, verwenden Sie VisualTreeHelper.GetChild , um das angewendete Vorlagenstammobjekt abzurufen. Dann können Sie FindName für dieses Stammobjekt aufrufen, und Sie suchen das XAML-Namescope der Vorlage und nicht die größere Seite.

Name und Datenbindung

Sie können den Zeichenfolgenwert von Name nicht als direkten Quellwert für eine Datenbindungsquelle verwenden. Wenn Sie denselben Zeichenfolgenwert wie Name in der Benutzeroberfläche mit Bindung anzeigen müssen, sollten Sie denselben Wert in die Tag-Eigenschaft replizieren, die als Eigenschaftsbindungsquelle verwendet werden kann. Verwenden Sie Auch Name nicht als Bindungsziel.

Der Wert von x:Name oder Name ist der Bezeichner, den Sie zum Identifizieren des Quellelements für eine ElementName-Bindung verwenden. Weitere Informationen finden Sie unter Datenbindung im Detail.

Festlegen des Namens im Code

Sie können den Wert von Name für ein Objekt zur Laufzeit festlegen, aber es gibt einige wichtige Überlegungen und Einschränkungen, die Sie beachten sollten.

Das Ändern des Werts von Name im Code zur Laufzeit, wenn für das Objekt ein vorheriger Name-Wert in XAML festgelegt wurde, wird in der Regel nicht empfohlen. Dies liegt daran, dass das Festlegen eines Namens nach dem Laden der Objektstruktur den identifizierenden Namen des entsprechenden Feldverweises nicht erstellt oder geändert wird. Wenn bereits ein Feldverweis vorhanden ist, weil x:Name im anfänglichen Markup angegeben wird, und Sie den Wert von Name ändern, sind das Feld und der Name, den Sie zum Suchen des Objekts über FindName verwenden müssen, jetzt unterschiedlich, da das Feld als der mit dem Markup definierte Name bleibt.

Das Festlegen eines Name-Werts für ein Objekt, das im Code erstellt wurde und daher nie einen XAML-definierten Name-Wert hatte, ist für bestimmte Szenarien geeignet. Ein solches Szenario ist, wenn Sie entweder XAML-erstellte oder code-erstellte Objekte in der Struktur finden möchten, indem Sie FindName als allgemeine Hilfsprogrammfunktion verwenden. Damit dieses Szenario funktioniert, wird vom Windows-Runtime zur Laufzeit weiterhin verwendet und der XAML-Namescope-Hashtabellendarstellung hinzugefügt. Wenn Sie versuchen, einer vorhandenen, größtenteils von XAML erstellten Objektstruktur neue benannte Objekte hinzuzufügen, müssen Namen eindeutig sein, andernfalls tritt eine Ausnahme für doppelte Namen auf. Die Ausnahme des doppelten Namens tritt möglicherweise nicht auf, wenn Sie versuchen, Name festzulegen. Bis Sie versuchen, das duplizierte Objekt der Standard Objektstruktur hinzuzufügen, verfügt das neue Objekt über einen eigenen eigenständigen XAML-Namescope. Erst in dem Moment, in dem Sie das Objekt mit einer größeren Objektstruktur verbinden, kann die Bedingung für den doppelten Namen erkannt werden. Oder die Ausnahme kann für den Vorgang auftreten, der Objekte in der Struktur verbunden hat, z. B. bei einem Aufruf der Add-Methode einer Auflistung, die eine Verbindung mit der Standard Objektstruktur herstellt.

Es kann schwierig sein zu wissen, welche Name-Werte bereits im XAML-Namescope vorhanden sind, dem Sie das neue Objekt später hinzufügen werden. Es gibt keine spezifische API, die die vollständige Hashtabelle vorhandener Namen in einem XAML-Namescope meldet. Wenn Sie Name-Werte im Code ausführlich festlegen, benötigen Sie möglicherweise eine Technik zum Generieren von Namenszeichenfolgen, die für Ihre Laufzeitnutzung eindeutig sind, oder Sie müssen Aufrufe umschließen, die neu benannte Objekte in einem Try-Catch-Block hinzufügen, um die Ausnahmen abzufangen, die sich aus einem doppelten Namen ergeben können. Oder Sie können der InitializeComponent-Implementierung , die die XAML-generierten Namenwerte liest, Ihren eigenen Code hinzufügen.

Beachten Sie, dass Sie Name nur zur Laufzeit für Objekte festlegen können, die ein FrameworkElement oder eine Inline sind. Wenn ein Objekt keine Name-Eigenschaft aufweist und das Festlegen des Namens in XAML die Verwendung des x:Name-Attributs anstelle von Name erfordert hätte, ist keine Laufzeit-API zum Festlegen des Laufzeitnamens eines solchen Objekts verfügbar.

Gilt für:

Weitere Informationen