x:Name — dyrektywa

  • Artykuł

Unikatowo identyfikuje elementy zdefiniowane przez język XAML w nazwie XAML. Zakresy nazw XAML i ich modele unikatowości można zastosować do utworzonych obiektów, gdy struktury zapewniają interfejsy API lub implementują zachowania, które uzyskują dostęp do grafu obiektów utworzonego przez XAML w czasie wykonywania.

Użycie atrybutu języka XAML

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

Wartości XAML

Wartość Opis
XAMLNameValue Ciąg zgodny z ograniczeniami gramatyki XamlName.

Uwagi

Po x:Name zastosowaniu do modelu programowania opartego na strukturze nazwa jest równoważna zmiennej, która zawiera odwołanie do obiektu lub wystąpienie zwracane przez konstruktora.

Wartość x:Name użycia dyrektywy musi być unikatowa w obrębie zakresu nazw XAML. Domyślnie w przypadku użycia przez interfejs API usług XAML platformy .NET podstawowy zakres nazw XAML jest definiowany w głównym elemenderze XAML pojedynczego środowiska produkcyjnego XAML i obejmuje elementy zawarte w tej produkcji XAML. Dodatkowe dyskretne zakresy nazw XAML, które mogą wystąpić w ramach pojedynczej produkcji XAML, można zdefiniować przez struktury w celu rozwiązania określonych scenariuszy. Na przykład w WPF nowe zakresy nazw XAML są definiowane i tworzone przez dowolny szablon, który jest również zdefiniowany w tej produkcji XAML. Aby uzyskać więcej informacji o nazwach XAML (napisanych dla WPF, ale istotnych dla wielu pojęć dotyczących nazw XAML), zobacz WPF XAML Namescopes.

Ogólnie rzecz biorąc, x:Name nie należy stosować w sytuacjach, w których jest również używana wartość x:Key. Implementacje XAML według określonych istniejących struktur wprowadziły koncepcje podstawień między x:Key i x:Name, ale nie jest to zalecana praktyka. Usługi XAML platformy .NET nie obsługują takich koncepcji podstawienia podczas obsługi informacji o nazwie/kluczu, takich jak INameScope lub DictionaryKeyPropertyAttribute.

Reguły dotyczące zezwolenia x:Name na wymuszanie unikatowości nazw są potencjalnie definiowane przez określone struktury implementowania. Jednak aby można było używać w usługach XAML platformy .NET, definicje unikatowości zakresu nazw XAML powinny być zgodne z definicją INameScope informacji w tej dokumentacji i powinny używać tych samych reguł dotyczących miejsca zastosowania informacji. Na przykład implementacja programu Windows Presentation Foundation (WPF) dzieli różne elementy znaczników na oddzielne NameScope zakresy, takie jak słowniki zasobów, drzewo logiczne utworzone przez kod XAML na poziomie strony, szablony i inne odroczone treści, a następnie wymusza unikatowość nazw XAML w każdym z tych zakresów nazw XAML.

W przypadku typów niestandardowych korzystających z składników zapisywania obiektów XAML usług .NET XAML można ustanowić lub zmienić właściwość mapowania na x:Name typ. To zachowanie definiuje się, odwołując się do nazwy właściwości do mapowania za pomocą RuntimeNamePropertyAttribute kodu definicji typu. RuntimeNamePropertyAttribute jest atrybutem na poziomie typu.

Using.NET usług XAML logika tworzenia kopii zapasowych dla obsługi zakresu nazw XAML może być zdefiniowana w sposób neutralny dla struktury przez zaimplementowanie interfejsu INameScope .

Uwagi dotyczące użycia platformy WPF

W standardowej konfiguracji kompilacji dla aplikacji WPF, która używa języka XAML, klas częściowych i kodu za pomocą kodu, określona x:Name staje się nazwą pola utworzonego w kodzie bazowym, gdy kod XAML jest przetwarzany przez zadanie kompilacji znaczników, a to pole zawiera odwołanie do obiektu. Domyślnie utworzone pole jest wewnętrzne. Dostęp do pola można zmienić, określając atrybut x:FieldModifier. W środowiskach WPF i Silverlight sekwencja polega na tym, że kompilator znaczników definiuje i nazywa pole w klasie częściowej, ale wartość jest początkowo pusta. Następnie wygenerowana metoda o nazwie InitializeComponent jest wywoływana z poziomu konstruktora klasy. InitializeComponentFindName składa się z wywołań używających każdej z x:Name wartości, które istnieją w zdefiniowanej przez XAML części klasy częściowej jako ciągi wejściowe. Zwracane wartości są następnie przypisywane do odwołania do pola o podobnej nazwie, aby wypełnić wartości pól obiektami utworzonymi na podstawie analizy kodu XAML. Wykonanie InitializeComponent polecenia umożliwia odwołanie do grafu obiektu czasu wykonywania przy użyciu x:Name nazwy /pola bezpośrednio, a nie konieczności wywoływania FindName jawnie za każdym razem, gdy potrzebujesz odwołania do obiektu zdefiniowanego w języku XAML.

W przypadku aplikacji WPF, która korzysta z obiektów docelowych języka Microsoft Visual Basic i zawiera pliki XAML z Page akcją kompilacji, tworzona jest oddzielna właściwość odwołania, która dodaje WithEvents słowo kluczowe do wszystkich elementów, które mają element x:Name, w celu obsługi Handles składni dla delegatów procedury obsługi zdarzeń. Ta właściwość jest zawsze publiczna. Aby uzyskać więcej informacji, zobacz Visual Basic i WPF Event Handling (Obsługa zdarzeń w języku Visual Basic i WPF).

x:Name jest używany przez procesor XAML WPF do zarejestrowania nazwy w zakresie nazw XAML w czasie ładowania, nawet w przypadkach, gdy strona nie jest skompilowana przez akcje kompilacji (na przykład luźne XAML słownika zasobów). Jednym z powodów tego zachowania jest to, że x:Name element jest potencjalnie potrzebny do ElementName powiązania. Aby uzyskać szczegółowe informacje, zobacz Omówienie powiązania danych.

Jak wspomniano wcześniej, x:Name (lub Name) nie należy stosować w sytuacjach, które również używają .x:Key WPF ResourceDictionary ma specjalne zachowanie definiujące się jako zakres nazw XAML, ale zwracanie wartości Not Implement lub null dla INameScope interfejsów API jako sposób wymuszania tego zachowania. Jeśli analizator XAML WPF napotka Name lub x:Name w zdefiniowanym ResourceDictionaryjęzyku XAML, nazwa nie zostanie dodana do żadnego zakresu nazw XAML. Próba znalezienia tej nazwy z dowolnego zakresu nazw XAML i FindName metody nie będą zwracać prawidłowych wyników.

x:Nazwa i nazwa

Wiele scenariuszy aplikacji WPF może uniknąć dowolnego użycia atrybutu x:Name , ponieważ Name właściwość zależności określona w domyślnej przestrzeni nazw XAML dla kilku ważnych klas bazowych, takich jak FrameworkElement i FrameworkContentElement spełnia ten sam cel. Nadal istnieją pewne typowe scenariusze XAML i WPF, w których dostęp kodu do elementu bez Name właściwości na poziomie struktury jest ważny. Na przykład niektóre klasy obsługi animacji i scenorysu nie obsługują Name właściwości, ale często muszą się odwoływać w kodzie w celu kontrolowania animacji. Należy określić x:Name jako atrybut na osiach czasu i przekształceniach utworzonych w języku XAML, jeśli zamierzasz odwoływać się do nich z kodu później.

Jeśli Name jest dostępna jako właściwość klasy Name i x:Name może być używana zamiennie jako atrybuty, ale wyjątek analizy spowoduje, jeśli oba są określone w tym samym elemencie. Jeśli kod XAML jest skompilowany, wyjątek wystąpi w kompilacji znaczników, w przeciwnym razie wystąpi podczas ładowania.

Name Można ustawić przy użyciu składni atrybutów XAML i w kodzie przy użyciu SetValue; należy jednak pamiętać, że ustawienie Name właściwości w kodzie nie powoduje utworzenia odwołania do pola reprezentatywnego w zakresie nazw XAML w większości przypadków, gdy kod XAML jest już załadowany. Zamiast próbować ustawić Name w kodzie, użyj NameScope metod z kodu względem odpowiedniego zakresu nazw.

Name można również ustawić przy użyciu składni elementu właściwości z tekstem wewnętrznym, ale jest to nietypowe. Z kolei x:Name nie można ustawić w składni elementu właściwości XAML lub w kodzie przy użyciu SetValue; można go ustawić tylko przy użyciu składni atrybutu dla obiektów, ponieważ jest to dyrektywa.

Informacje o użyciu programu Silverlight

x:Name Program Silverlight jest udokumentowany oddzielnie. Aby uzyskać więcej informacji, zobacz Funkcje języka XAML (x:) Language Features (Silverlight).

Zobacz też