PropertyPath — Składnia XAML

Artykuł
10/18/2023

Obiekt PropertyPath obsługuje złożoną składnię XAML wbudowanej do ustawiania różnych właściwości, które przyjmują PropertyPath typ jako wartość. Ten temat zawiera informacje o składni stosowanej PropertyPath do składni powiązań i animacji.

Gdzie jest używana właściwośćPath

PropertyPath jest typowym obiektem używanym w kilku funkcjach programu Windows Presentation Foundation (WPF). Pomimo używania wspólnych PropertyPath do przekazywania informacji o ścieżce właściwości, użycie każdego obszaru funkcji, w którym PropertyPath jest używany jako typ, różnią się. W związku z tym bardziej praktyczne jest udokumentowanie składni na podstawie poszczególnych funkcji.

Przede wszystkim WPF używa PropertyPath do opisywania ścieżek modelu obiektów na potrzeby przechodzenia właściwości źródła danych obiektu i opisywania ścieżki docelowej dla docelowych animacji.

Niektóre właściwości stylu i szablonu, takie jak Setter.Property nazwa kwalifikowanej właściwości, która powierzchownie przypomina PropertyPath. Ale nie jest to prawda PropertyPath; zamiast tego jest to kwalifikowane użycie formatu ciągu owner.property , które jest włączone przez procesor WPF XAML w połączeniu z konwerterem typów dla DependencyProperty.

PropertyPath dla obiektów w powiązaniu danych

Powiązanie danych to funkcja WPF, w której można powiązać wartość docelową dowolnej właściwości zależności. Jednak źródło takiego powiązania danych nie musi być właściwością zależności; może to być dowolny typ właściwości rozpoznawany przez odpowiedniego dostawcę danych. Ścieżki właściwości są szczególnie używane dla ObjectDataProviderobiektu , który jest używany do uzyskiwania źródeł powiązań z obiektów środowiska uruchomieniowego języka wspólnego (CLR) i ich właściwości.

Należy pamiętać, że powiązanie danych z plikiem XML nie używa PropertyPathelementu , ponieważ nie jest używane Path w pliku Binding. Zamiast tego należy użyć XPath i określić prawidłową składnię XPath do modelu DOM (XML Document Object Model) danych. XPath jest również określony jako ciąg, ale nie jest tutaj udokumentowany; zobacz Tworzenie powiązania z danymi XML przy użyciu elementu XMLDataProvider i zapytań XPath.

Kluczem do zrozumienia ścieżek właściwości w powiązaniu danych jest to, że można określić powiązanie z pojedynczą wartością właściwości lub zamiast tego można powiązać z właściwościami docelowymi, które przyjmują listy lub kolekcje. Jeśli kolekcje są powiązaniami, na przykład powiązanie ListBox elementu, które będzie rozszerzać się w zależności od liczby elementów danych w kolekcji, ścieżka właściwości powinna odwoływać się do obiektu kolekcji, a nie pojedynczych elementów kolekcji. Aparat powiązania danych będzie pasował do kolekcji używanej jako źródło danych do typu docelowego powiązania automatycznie, co powoduje zachowanie, takie jak wypełnianie ListBox tablicy elementów.

Pojedyncza właściwość obiektu natychmiastowego jako kontekstu danych

<Binding Path="propertyName" ... />

propertyName musi być nazwą właściwości, która znajduje się w bieżącym DataContext przypadku Path użycia. Jeśli powiązanie aktualizuje źródło, ta właściwość musi być odczytywana/zapisywana, a obiekt źródłowy musi być modyfikowalny.

Pojedynczy indeksator w bezpośrednim obiekcie jako kontekst danych

<Binding Path="[key]" ... />

key musi być indeksem wpisanym do słownika lub tabeli skrótu albo indeksem całkowitym tablicy. Ponadto wartość klucza musi być typem, który jest bezpośrednio powiązany z właściwością, w której jest stosowany. Na przykład można użyć tabeli skrótów zawierającej klucze ciągów i wartości ciągów w ten sposób, aby powiązać element Text z elementem TextBox. Lub jeśli klucz wskazuje kolekcję lub podindeks, możesz użyć tej składni do powiązania z docelową właściwością kolekcji. W przeciwnym razie należy odwołać się do określonej właściwości za pomocą składni, takiej jak <Binding Path="[key].propertyName" .../>.

W razie potrzeby można określić typ indeksu. Aby uzyskać szczegółowe informacje na temat tego aspektu ścieżki właściwości indeksowanej, zobacz Binding.Path.

Wiele właściwości (określanie wartości docelowej właściwości pośredniej)

<Binding Path="propertyName.propertyName2" ... />

propertyName Musi być rozpoznawana jako nazwa właściwości, która jest bieżącą wartością DataContext. Właściwości propertyName ścieżki i propertyName2 mogą być dowolnymi właściwościami, które istnieją w relacji, gdzie propertyName2 jest właściwością, która istnieje w typie, który jest wartością propertyName.

Pojedyncza właściwość, dołączona lub kwalifikowana w inny sposób

<object property="(ownerType.propertyName)" ... />

Nawiasy wskazują, że ta właściwość w obiekcie PropertyPath powinna zostać skonstruowana przy użyciu częściowej kwalifikacji. Może użyć przestrzeni nazw XML, aby znaleźć typ z odpowiednim mapowaniem. Typy ownerType wyszukiwania, do których procesor XAML ma dostęp za pośrednictwem XmlnsDefinitionAttribute deklaracji w każdym zestawie. Większość aplikacji ma domyślną przestrzeń nazw XML zamapowana na http://schemas.microsoft.com/winfx/2006/xaml/presentation przestrzeń nazw, dlatego prefiks jest zwykle wymagany tylko dla typów niestandardowych lub typów poza tą przestrzenią nazw. propertyName musi być rozpoznawana jako nazwa właściwości istniejącej na ownerTypeobiekcie . Ta składnia jest zwykle używana w jednym z następujących przypadków:

Ścieżka jest określona w języku XAML, który jest w stylu lub szablonie, który nie ma określonego typu docelowego. Użycie kwalifikowane jest zwykle nieprawidłowe w przypadkach innych niż ten, ponieważ w przypadkach innych niż szablony właściwość istnieje na wystąpieniu, a nie typ.
Właściwość jest dołączoną właściwością.
Powiązanie jest wiązane z właściwością statyczną.

W przypadku użycia jako obiektu docelowego scenorysu właściwość określona jako propertyName musi być .DependencyProperty

Przechodzenie źródłowe (powiązanie z hierarchiami kolekcji)

<object Path="propertyName/propertyNameX" ... />

/ w tej składni służy do nawigowania w obiekcie hierarchicznego źródła danych, a wiele kroków do hierarchii z kolejnymi / znakami są obsługiwane. Źródłowe konta przechodzenia dla bieżącego położenia wskaźnika rekordu, który jest określany przez synchronizowanie danych z interfejsem użytkownika jego widoku. Aby uzyskać szczegółowe informacje na temat powiązania z hierarchicznymi obiektami źródła danych i pojęcia bieżącego wskaźnika rekordu w powiązaniu danych, zobacz Use the Master-Detail Pattern with Hierarchical Data or Data Binding Overview (Używanie wzorca szczegółów z hierarchicznymi danymi lub powiązaniem danych).

Uwaga

Powierzchownie ta składnia przypomina XPath. Prawdziwe wyrażenie XPath do powiązania ze źródłem danych XML nie jest używane jako Path wartość i zamiast tego powinno być używane dla właściwości wzajemnie wykluczających XPath się.

Widoki kolekcji

Aby odwołać się do nazwanego widoku kolekcji, prefiks nazwy widoku kolekcji z znakiem skrótu (#).

Bieżący wskaźnik rekordu

Aby odwołać się do bieżącego wskaźnika rekordu dla widoku kolekcji lub głównego scenariusza powiązania danych szczegółów, uruchom ciąg ścieżki za pomocą ukośnika (/). Każda ścieżka obok ukośnika jest przechodzina począwszy od bieżącego wskaźnika rekordu.

Wiele indeksatorów

<object Path="[index1,index2...]" ... />

lub

<object Path="propertyName[index,index2...]" ... />

Jeśli dany obiekt obsługuje wiele indeksatorów, te indeksatory można określić w kolejności, podobnie jak składnia odwołująca się do tablicy. Dany obiekt może być bieżącym kontekstem lub wartością właściwości zawierającej wiele obiektów indeksu.

Domyślnie wartości indeksatora są wpisywane przy użyciu cech obiektu bazowego. W razie potrzeby można określić typ indeksu. Aby uzyskać szczegółowe informacje na temat wpisywania indeksatorów, zobacz Binding.Path.

Mieszanie składni

Każda ze składni pokazanych powyżej może być przeplatane. Na przykład poniżej przedstawiono przykład, który tworzy ścieżkę właściwości do koloru w określonym x,y ColorGrid właściwości zawierającej tablicę SolidColorBrush siatki pikseli obiektów:

<Rectangle Fill="{Binding ColorGrid[20,30].SolidColorBrushResult}" ... />

Ucieczki dla ciągów ścieżki właściwości

W przypadku niektórych obiektów biznesowych może wystąpić przypadek, w którym ciąg ścieżki właściwości wymaga sekwencji ucieczki w celu poprawnego analizowania. Konieczność ucieczki powinna być rzadka, ponieważ wiele z tych znaków ma podobne problemy z interakcją nazewnictwa w językach, które zwykle będą używane do definiowania obiektu biznesowego.

Wewnątrz indeksatorów ([ ]) znak karetki (^) unika następnego znaku.
Należy użyć ucieczki (przy użyciu jednostek XML) określonych znaków, które są specjalne dla definicji języka XML. Użyj & polecenia , aby uciec od znaku "&". Użyj > polecenia , aby uniknąć tagu końcowego ">".
Należy użyć znaków ucieczki (przy użyciu ukośnika \odwrotnego), które są specjalne dla zachowania analizatora WPF XAML do przetwarzania rozszerzenia znaczników.
- Ukośnik odwrotny (\) to sam znak ucieczki.
- Znak równości (=) oddziela nazwę właściwości od wartości właściwości.
- Przecinek (,) oddziela właściwości.
- Prawy nawias klamrowy (}) to koniec rozszerzenia znaczników.

Uwaga

Technicznie te ucieczki działają również dla ścieżki właściwości scenorysu, ale zwykle przechodzisz przez modele obiektów dla istniejących obiektów WPF i ucieczka powinna być niepotrzebna.

PropertyPath dla obiektów docelowych animacji

Właściwość docelowa animacji musi być właściwością zależności, która przyjmuje Freezable typ pierwotny lub . Jednak właściwość docelowa typu i ostateczna animowana właściwość może istnieć na różnych obiektach. W przypadku animacji ścieżka właściwości służy do definiowania połączenia między właściwością obiektu docelowego o nazwie animacji a docelową właściwością animacji zamierzonej przez przechodzenie relacji właściwości-obiektów w wartościach właściwości.

Ogólne zagadnienia dotyczące właściwości obiektu dla animacji

Aby uzyskać więcej informacji na temat ogólnych pojęć dotyczących animacji, zobacz Storyboards Overview and Animation Overview (Omówienie scenorysów i animacji — omówienie).

Typ wartości lub animowana właściwość musi być typem lub elementem Freezable pierwotnym. Właściwość rozpoczynająca ścieżkę musi być rozpoznawana jako nazwa właściwości zależności, która istnieje w określonym TargetName typie.

Aby można było obsługiwać klonowanie w celu animowania Freezable obiektu, który jest już zamrożony, obiekt określony przez TargetName musi być klasą lub FrameworkContentElement pochodnąFrameworkElement.

Pojedyncza właściwość obiektu docelowego

<animation Storyboard.TargetProperty="propertyName" ... />

propertyName Musi być rozpoznawana jako nazwa właściwości zależności, która istnieje w określonym TargetName typie.

Określanie wartości docelowej właściwości pośredniej

<animation Storyboard.TargetProperty="propertyName.propertyName2" ... />

propertyName musi być właściwością, która jest typem Freezable wartości lub elementem pierwotnym, który istnieje w określonym TargetName typie.

propertyName2 musi być nazwą właściwości zależności, która istnieje w obiekcie, który jest wartością propertyName. Innymi słowy, propertyName2 musi istnieć jako właściwość zależności dla typu , który jest propertyNamePropertyType.

Bezpośrednie kierowanie animacji jest konieczne ze względu na zastosowane style i szablony. W celu kierowania animacji potrzebny jest TargetName obiekt docelowy i ta nazwa jest ustanawiana przez x:Name lub Name. Chociaż elementy szablonu i stylu mogą również mieć nazwy, nazwy te są prawidłowe tylko w zakresie nazw stylu i szablonu. (Jeśli szablony i style współużytkował zakresy nazw przy użyciu znaczników aplikacji, nazwy nie mogą być unikatowe. Style i szablony są dosłownie udostępniane między wystąpieniami i utrwalają zduplikowane nazwy). W związku z tym, jeśli poszczególne właściwości elementu, które można animować, pochodzą ze stylu lub szablonu, musisz zacząć od nazwanego wystąpienia elementu, które nie pochodzi z szablonu stylu, a następnie kierować do stylu lub drzewa wizualnego szablonu, aby uzyskać właściwość, którą chcesz animować.

Na przykład Background właściwość elementu Panel jest kompletna Brush (faktycznie element ), SolidColorBrushktóra pochodzi z szablonu motywu. Aby animować Brush całkowicie, musiałby istnieć BrushAnimation (prawdopodobnie jeden dla każdego Brush typu) i nie ma takiego typu. Aby animować pędzla, zamiast animować właściwości określonego Brush typu. Musisz dostać się z SolidColorBrush do jego Color , aby zastosować ColorAnimation tam. Ścieżka właściwości dla tego przykładu to Background.Color.

Dołączone właściwości

<animation Storyboard.TargetProperty="(ownerType.propertyName)" ... />

Nawiasy wskazują, że ta właściwość w obiekcie PropertyPath powinna zostać skonstruowana przy użyciu częściowej kwalifikacji. Może ona użyć przestrzeni nazw XML, aby znaleźć typ. Typy ownerType wyszukiwania, do których procesor XAML ma dostęp za pośrednictwem XmlnsDefinitionAttribute deklaracji w każdym zestawie. Większość aplikacji ma domyślną przestrzeń nazw XML zamapowana na http://schemas.microsoft.com/winfx/2006/xaml/presentation przestrzeń nazw, dlatego prefiks jest zwykle wymagany tylko dla typów niestandardowych lub typów poza tą przestrzenią nazw. propertyName musi być rozpoznawana jako nazwa właściwości istniejącej na ownerTypeobiekcie . Właściwość określona jako propertyName musi być .DependencyProperty (Wszystkie właściwości dołączone WPF są implementowane jako właściwości zależności, więc ten problem dotyczy tylko niestandardowych dołączonych właściwości).

Indexers (Indeksatory)

<animation Storyboard.TargetProperty="propertyName.propertyName2[index].propertyName3" ... />

Większość właściwości lub Freezable typów zależności nie obsługuje indeksatora. Dlatego jedynym użyciem indeksatora w ścieżce animacji jest położenie pośrednie między właściwością, która uruchamia łańcuch w nazwanym obiekcie docelowym i ewentualną animowaną właściwością. W podanej składni jest to propertyName2. Na przykład użycie indeksatora może być konieczne, jeśli właściwość pośrednia jest kolekcją, taką jak TransformGroup, w ścieżce właściwości, takiej jak RenderTransform.Children[1].Angle.

PropertyPath w kodzie

Użycie kodu dla programu PropertyPath, w tym sposób konstruowania elementu PropertyPath, jest udokumentowane w temacie referencyjnym dla programu PropertyPath.

Ogólnie rzecz biorąc, PropertyPath jest przeznaczony do używania dwóch różnych konstruktorów, jeden dla użycia powiązań i najprostszych użycia animacji oraz jeden dla złożonych zastosowań animacji. PropertyPath(Object) Użyj podpisu dla powiązań użycia, gdzie obiekt jest ciągiem. PropertyPath(Object) Użyj podpisu dla ścieżek animacji jednoetapowej, gdzie obiekt jest DependencyProperty. Użyj podpisu dla PropertyPath(String, Object[]) złożonych animacji. Ten ostatni konstruktor używa ciągu tokenu dla pierwszego parametru i tablicy obiektów, które wypełniają pozycje w ciągu tokenu, aby zdefiniować relację ścieżki właściwości.