FrameworkElement.Name Eigenschaft

  • Referenz

Definition

Namespace:
Microsoft.UI.Xaml
Bearbeiten

Ruft den identifizierenden Namen des Objekts ab oder legt diese 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 zielen auf eine Animation ab, 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();
}

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 Fällen 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 als XAML-Attribute gegenseitig aus. Wenn Sie versuchen, sowohl als auch x:NameName für dasselbe Objektelement im Markup festzulegen, wird ein Parserfehler ausgelöst.

Wenn Sie die standardmäßigen Seitenbuildaktionen für XAML verwenden, werden alle XAML-Elemente, die über ein x:Name-Attribut verfügen oder Name Feldverweise generieren, die schließlich mit InitializeComponent aufgefüllt werden, wenn das XAML geladen wird. Die Feldverweise ermöglichen ein Programmiermodell, bei dem objekte direkt anhand des Namens in Ihrem seitenspezifischen CodeBehind referenziert werden können, nachdem die XAML-Objektstruktur in eine Seite oder App geladen wurde.

Namen müssen in einem XAML-Namescope eindeutig sein. Im Allgemeinen wird der 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 niemals lokalisiert werden. Name wird als Feldnamensvariable im 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, obwohl dies von Ihrem Bereitstellungsmodell und den Lokalisierungsverfahren abhängt. Dies ist ein Grund, warum Sie keine Zeichenfolgen anzeigen sollten, die von Name auf der Benutzeroberfläche Ihrer App stammen.

Szenarien für Name

Das Festlegen x:Name oder Name im XAML-Code, der UI-Elemente definiert, unterstützt mehrere Hauptszenarien:

  • Animationsziel Um eine Animation auf eine Objekteigenschaft anzuwenden, müssen Sie eine bestimmte instance als Ziel verwenden. 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 Namezugewiesen haben. Weitere Informationen finden Sie unter Storyboardanimationen.
  • Teile einer Steuerelementvorlage Um das visuelle Zustandsmodell und die Steuerelementinitialisierung zu unterstützen, sollten Autoren von Steuerelementen Werte für die wichtigsten Teile eines steuerelements in Vorlagen angeben Name . Weitere Informationen finden Sie unter XAML-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 auf einem anderen ui-Element in der Nähe. Die einfachste Möglichkeit, Code für diese Situation zu schreiben, besteht darin, den feldverweis zu verwenden, der aus einem Namegeneriert wird.

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 von XAML erstellte Objektstruktur in ihrer Gesamtheit. FindName Technisch gesehen wird tatsächlich der XAML-Namescope gesucht, der die Strukturmetapher nicht beibekommt und stattdessen als Hashtabelle mit Namen dargestellt wird. FindName Namen, die in angewendeten Vorlagen definiert sind, können nicht gefunden werden. Um Elemente in angewendeten Vorlagen zu finden, verwenden Sie VisualTreeHelper.GetChild , um das angewendete Vorlagenstammobjekt abzurufen. Anschließend können Sie für dieses Stammobjekt aufrufen FindName , und Sie durchsuchen den XAML-Namensbereich 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 den gleichen 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 Name auch nicht als Bindungsziel.

Der Wert von x:Name oder Name ist der Bezeichner, den Sie verwenden, um das Quellelement für eine ElementName-Bindung zu identifizieren. Weitere Informationen finden Sie unter Datenbindung im Detail.

Festlegen des Namens im Code

Sie können den Wert für Name ein Objekt zur Laufzeit festlegen, es gibt jedoch 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 im Allgemeinen nicht empfohlen. Dies liegt daran, dass das Festlegen eines Namens nach dem Laden der Objektstruktur den identifizierenden Namen des entsprechenden Feldverweises nicht erstellt oder ändert. Wenn bereits ein Feldverweis vorhanden ist, da x:Name im ursprünglichen Markup angegeben wird, und Sie den Wert von Nameändern, sind das Feld und der Name, den Sie verwenden müssen, um das Objekt über FindName zu finden, jetzt unterschiedlich, da das Feld als der durch Markup definierte Name erhalten bleibt.

Das Festlegen eines Name Werts für ein Objekt, das im Code erstellt wurde und daher nie über einen XAML-definierten Name-Wert verfügt, ist für bestimmte Szenarien geeignet. Ein solches Szenario ist, wenn Sie mithilfe von FindName als allgemeine Hilfsprogrammfunktion entweder xaml- oder code-erstellte Objekte in der Struktur finden möchten. Damit dieses Szenario funktioniert, verwendet der Windows-Runtime weiterhin die Hashtabellendarstellung des XAML-Namescopes zur Laufzeit und fügt sie hinzu. 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 mit doppelten Namen auf. Die Ausnahme mit doppeltem Namen tritt möglicherweise nicht auf, wenn versucht wird, festzulegen Name. Bis Sie versuchen, das duplizierte benannte 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 doppelte Namen erkannt werden. Oder die Ausnahme kann bei dem 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 umfassend 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 Implementierung, die die InitializeComponent von XAML generierten Namenswerte liest, Ihren eigenen Code hinzufügen.

Beachten Sie, dass Sie zur Laufzeit nur für Objekte festlegen Name können, bei denen es sich um ein FrameworkElement oder ein Inline handelt. Wenn ein Objekt über keine Name -Eigenschaft verfügt und das Festlegen des Namens in XAML anstelle des x:Name -Attributs Nameerforderlich wäre, ist keine Laufzeit-API zum Festlegen des Laufzeitnamens eines solchen Objekts verfügbar.

Gilt für:

Weitere Informationen