PropertyPath — Składnia XAML

Obiekt PropertyPath obsługuje złożoną składnię w tekście do ustawiania różnych właściwości, które XAML mają typ jako PropertyPath wartość. W tym temacie o PropertyPath dokumentach o składni zastosowanej do składni powiązania i animacji.

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

PropertyPath jest wspólnym obiektem używanym w kilku Windows Presentation Foundation (WPF) funkcjach. Pomimo używania wspólnego do przekazywania informacji o ścieżce właściwości, użycie dla każdego obszaru funkcji, w którym jest używany PropertyPath PropertyPath jako typ, jest różne. W związku z tym bardziej praktyczne jest dokumentować składnie dla większej liczby funkcji.

Używa przede wszystkim do opisywania ścieżek modelu obiektów do przechodzenia przez właściwości źródła danych obiektu oraz do opisywania ścieżki docelowej dla WPF PropertyPath animacji docelowych.

Niektóre właściwości stylu i szablonu, takie jak take kwalifikowaną nazwę właściwości, która w sposób Setter.Property powierzchowy przypomina obiekt PropertyPath . Ale to nie jest prawda; zamiast tego jest to kwalifikowane użycie formatu ciągu PropertyPath owner.property, które jest włączane przez procesor WPF w połączeniu z konwerterem XAML typów dla DependencyProperty .

PropertyPath dla obiektów w powiązaniu danych

Powiązanie danych to WPF funkcja, za pomocą której można powiązać z wartością docelową dowolnej właściwości zależności. Jednak źródłem takiego powiązania danych nie musi być właściwość 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 obiektu , który służy do uzyskiwania źródeł powiązań z obiektów środowiska uruchomieniowego języka wspólnego ObjectDataProvider (CLR) i ich właściwości.

Należy pamiętać, że powiązanie danych z kodem XML nie używa elementu PropertyPath , ponieważ nie jest ono wykorzystywane w pliku Path Binding . Zamiast tego należy użyć XPath i określić prawidłową składnię XPath w Document Object Model XML (DOM) danych. XPathjest również określony jako ciąg, ale nie jest udokumentowany w tym miejscu; Zobacz Wiązanie z danymi XML przy użyciu obiektu XMLDataProvider i zapytań XPath.

Kluczem do zrozumienia ścieżek właściwości w powiązaniu danych jest to, że można kierować powiązanie do poszczególnych wartości właściwości lub zamiast tego można powiązać je z właściwościami docelowymi, które biorą listy lub kolekcje. W przypadku powiązania kolekcji, na przykład powiązania obiektu , który zostanie rozszerzony w zależności od tego, ile elementów danych znajduje się w kolekcji, ścieżka właściwości powinna odwoływać się do obiektu kolekcji, a nie do pojedynczych elementów ListBox kolekcji. Aparat powiązania danych będzie automatycznie dorównać kolekcji używanej jako źródło danych do typu obiektu docelowego powiązania, co spowoduje zachowanie, takie jak wypełnienie obiektu ListBox tablicą elementów.

Pojedyncza właściwość obiektu bezpośredniego jako kontekstu danych

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

Właściwość propertyName musi być rozpoznawane jako nazwa właściwości, która znajduje się w bieżącej DataContext wartości Path użycia. Jeśli powiązanie aktualizuje źródło, ta właściwość musi być do odczytu/zapisu, a obiekt źródłowy musi być modyfikowalny.

Pojedynczy indeksator w obiekcie bezpośrednim jako kontekście danych

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

key musi być indeksem typicznym słownika lub tabeli skrótów albo indeksem liczb całkowitych tablicy. Ponadto wartość klucza musi być typem, który jest bezpośrednio wiązany z właściwością, w której jest stosowany. Na przykład tabela skrótów zawierająca klucze ciągów i wartości ciągów może być używana w ten sposób do powiązania z tekstem dla TextBox obiektu . Jeśli klucz wskazuje kolekcję lub indeks podrzędny, można użyć tej składni do powiązania z właściwością kolekcji docelowej. 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 indeksowanych, zobacz Binding.Path .

Wiele właściwości (docelowych właściwości pośrednich)

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

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

Pojedyncza właściwość, dołączona lub w inny Type-Qualified

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

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

  • Ścieżka jest określona w pliku , który jest w stylu lub szablonie, który nie XAML ma określonego typu docelowego. Kwalifikowane użycie zazwyczaj nie jest prawidłowe w przypadkach innych niż to, ponieważ w przypadkach innych niż szablonowe właściwość istnieje w wystąpieniu, a nie typie.

  • Właściwość jest właściwością dołączona.

  • Powiązanie jest z właściwością statyczną.

Aby można było używać jako obiektu docelowego storyboard, właściwość określona jako propertyName musi być DependencyProperty elementem .

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

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

/ w tej składni służy do nawigowania w obiekcie źródła danych hierarchicznych i wiele kroków do hierarchii z kolejnych / znaki są obsługiwane. Przechodzenie źródła odpowiada bieżącej pozycji wskaźnika rekordu, która jest określana przez synchronizowanie danych z interfejsem użytkownika widoku. Aby uzyskać szczegółowe informacje na temat powiązania z obiektami hierarchicznego źródła danych oraz koncepcję 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 Master-Detail danych hierarchicznych lub powiązania danych — omówienie).

Uwaga

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

Widoki kolekcji

Aby odwołać się do nazwanego widoku kolekcji, należy poprzeć nazwę widoku kolekcji znakiem skrótu ( # ).

Wskaźnik bieżącego rekordu

Aby odwołać się do bieżącego wskaźnika rekordu dla scenariusza powiązania danych widoku kolekcji lub szczegółów master, rozpocznij ciąg ścieżki ukośnikiem ( / ). Każda ścieżka po ukośniku jest przechodzina 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, można je określić w podanej kolejności, podobnie jak w przypadku tablicy odwołującej się do składni. Obiekt, o który chodzi, może być bieżącym kontekstem lub wartością właściwości, która zawiera wiele obiektów indeksu.

Domyślnie wartości indeksatora są typowane przy użyciu właściwości bazowego obiektu. 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żdą z powyższych składni można przeplatać. Na przykład poniżej przedstawiono przykład, który tworzy ścieżkę właściwości do koloru w określonym x,y właściwości zawierającej tablicę obiektów siatki ColorGrid SolidColorBrush pikseli:

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

Ucieczki 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 poprawnej analizy. Konieczność ucieczki powinna być rzadki, ponieważ wiele z tych znaków ma podobne problemy z nazewnictwem/interakcją w językach, które zwykle są używane do definiowania obiektu biznesowego.

  • Wewnątrz indeksatorów ([ ]) znak caret (^) unika następnego znaku.

  • Należy użyć ucieczki (przy użyciu jednostek XML) niektórych znaków, które są specjalne dla definicji języka XML. Użyj & , aby przed znakiem "&". Użyj > , aby uniknąć tagu końcowego ">".

  • Do przetwarzania rozszerzenia znaczników należy użyć znaków ucieczki (przy użyciu ukośnika odwrotnego), które są specjalne dla zachowania \ parsera XAML WPF.

    • 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 rzecz ujmując, te ucieczki również działają w przypadku ścieżki właściwości storyboard, ale zazwyczaj przechodzenie modeli obiektów dla istniejących obiektów WPF i ucieczka powinna być niepotrzebna.

Właściwość PropertyPath dla obiektów docelowych animacji

Właściwość docelowa animacji musi być właściwością zależności, która przyjmuje typ pierwotny Freezable lub . Jednak właściwość docelowa typu i właściwość animowana poszczególnych typów mogą 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ą nazwanego obiektu docelowego animacji a docelową właściwością animacji przez przechodzenie relacji właściwości obiektu w wartościach właściwości.

Ogólne Object-Property zagadnienia dotyczące animacji

Aby uzyskać więcej ogólnych informacji na temat pojęć dotyczących animacji, zobacz Storyboards Overview (Omówienie storyboards) i Animation Overview (Przegląd animacji).

Animowana właściwość lub typ wartości musi być Freezable typem lub prymitywem. Właściwość, która rozpoczyna ścieżkę, musi być rozpoznana jako nazwa właściwości zależności, która istnieje dla określonego TargetName typu.

Aby zapewnić obsługę klonowania w celu animowania obiektu, który jest już zamrożony, obiekt określony przez obiekt musi być Freezable TargetName klasą FrameworkElement FrameworkContentElement pochodną lub .

Pojedyncza właściwość obiektu docelowego

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

propertyName musi być rozpoznany jako nazwa właściwości zależności, która istnieje dla określonego TargetName typu.

Pośrednia właściwość określania wartości docelowej

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

propertyName musi być właściwością, która jest typem wartości Freezable 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 na obiekcie, który jest wartością propertyName . Innymi słowy, musi istnieć jako właściwość zależności dla propertyName2 typu , który jest propertyName PropertyType .

Pośrednie kierowanie animacji jest konieczne ze względu na zastosowane style i szablony. Aby uzyskać animację docelową, potrzebujesz obiektu na obiekcie docelowym, a ta nazwa TargetName jest ustalana przez x:Name lub Name . Chociaż elementy szablonu i stylu również mogą mieć nazwy, te nazwy są prawidłowe tylko w zakresie nazw stylu i szablonu. (Jeśli szablony i style współużytkowały zakresy nazw ze znacznikami aplikacji, nazwy nie mogły być unikatowe. Style i szablony są dosłownie współdzielone między wystąpieniami i utrwalałyby zduplikowane nazwy). W związku z tym, jeśli poszczególne właściwości elementu, które chcesz animować, pochodziły ze stylu lub szablonu, musisz zacząć od nazwanego wystąpienia elementu, które nie pochodzi z szablonu stylu, a następnie wywrzeć element docelowy w stylu lub drzewie wizualnym szablonu, aby dojść do właściwości, którą chcesz animować.

Na przykład właściwość Background obiektu jest kompletną Panel Brush (w rzeczywistości właściwością SolidColorBrush ), która pochodzi z szablonu motywu. Aby całkowicie animować obiektu , konieczne byłoby, aby był to typ BrushAnimation (prawdopodobnie jeden dla każdego typu) i Brush nie ma takiego Brush typu. Aby animować pędzla, zamiast tego animowane są właściwości określonego Brush typu. Aby zastosować w tym miejscu, należy pobrać SolidColorBrush z strony do tej Color ColorAnimation strony. Ścieżka właściwości w tym przykładzie to Background.Color .

Właściwości dołączone

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

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

Indexers (Indeksatory)

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

Większość właściwości lub typów zależności Freezable nie obsługuje indeksatora. W związku z tym jedyne użycie indeksatora w ścieżce animacji znajduje się na pośredniej pozycji między właściwością, która rozpoczyna łańcuch na nazwanej obiekcie docelowym, a docelową 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 klasy , w PropertyPath tym sposób konstruowania klasy , jest udokumentowane w PropertyPath temacie referencyjnym dla . PropertyPath

Ogólnie rzecz biorąc, projekt jest przeznaczony do używania dwóch różnych konstruktorów: jednego do użycia powiązań i najprostszych zastosowań animacji oraz jednego dla złożonych zastosowań PropertyPath animacji. Użyj PropertyPath(Object) sygnatury do powiązania użycia, gdzie obiekt jest ciągiem. Użyj PropertyPath(Object) sygnatury dla jednoetapowych ścieżek animacji, gdzie obiekt jest DependencyProperty obiektem . Użyj PropertyPath(String, Object[]) sygnatury dla złożonych animacji. Ten drugi konstruktor używa ciągu tokenu dla pierwszego parametru i tablicy obiektów, które wypełniają pozycje w ciągu tokenu w celu zdefiniowania relacji ścieżki właściwości.

Zobacz też