PropertyPath – syntaxe v jazyce XAML

Článek
10/18/2023

Objekt PropertyPath podporuje složitou vloženou syntaxi XAML pro nastavení různých vlastností, které přebírají PropertyPath typ jako jejich hodnotu. Toto téma dokumentuje syntaxi použitou PropertyPath pro syntaxi vazeb a animací.

Where PropertyPath se používá

PropertyPath je běžný objekt, který se používá v několika funkcích WPF (Windows Presentation Foundation). Navzdory použití společné PropertyPath k vyjádření informací o cestě vlastností se využití pro každou oblast funkcí, kde PropertyPath se používá jako typ, se liší. Proto je vhodnější zdokumentovat syntaxe na základě jednotlivých funkcí.

WpF primárně používá PropertyPath k popisu cest modelu objektu pro procházení vlastností zdroje dat objektu a k popisu cílové cesty pro cílené animace.

Některé vlastnosti stylu a šablony, jako Setter.Property je třeba vzít kvalifikovaný název vlastnosti, který povrchně připomíná .PropertyPath Ale to není pravda PropertyPath; místo toho jde o kvalifikované použití formátu řetězce owner.property , které je povoleno procesorem WPF XAML v kombinaci s převaděčem typů pro DependencyProperty.

PropertyPath pro objekty v datové vazbě

Datová vazba je funkce WPF, která umožňuje vytvořit vazbu na cílovou hodnotu jakékoli vlastnosti závislosti. Zdroj takové datové vazby však nemusí být vlastností závislosti; může být libovolný typ vlastnosti, který je rozpoznán příslušným poskytovatelem dat. Cesty vlastností se používají zejména pro objekty ObjectDataProviderCLR (Common Language Runtime), které se používají k získání zdrojů vazeb z objektů CLR (Common Language Runtime) a jejich vlastností.

Všimněte si, že datová vazba na XML se nepoužívá PropertyPath, protože se nepoužívá Path v objektu Binding. Místo toho použijete XPath a zadáte platnou syntaxi XPath do modelu DOM (Document Object Model) xml dat. XPath je také zadán jako řetězec, ale zde není zdokumentován; Viz Vazba na data XML pomocí XMLDataProvider a XPath Dotazy.

Klíčem k pochopení cest vlastností v datové vazbě je, že můžete vazbu cílit na hodnotu jednotlivé vlastnosti, nebo můžete vytvořit vazbu na cílové vlastnosti, které přebírají seznamy nebo kolekce. Pokud vytváříte vazby kolekcí, například vazba ListBox , která se rozšíří v závislosti na počtu datových položek v kolekci, měla by cesta k vlastnosti odkazovat na objekt kolekce, nikoli jednotlivé položky kolekce. Modul datových vazeb bude odpovídat kolekci použité jako zdroj dat s typem cíle vazby automaticky, což vede k chování, jako je naplnění ListBox polem položek.

Jedna vlastnost objektu okamžitého objektu jako kontext dat

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

vlastnost propertyName musí být přeložena jako název vlastnosti, která je v aktuálním DataContext stavu pro Path použití. Pokud vaše vazba aktualizuje zdroj, musí být tato vlastnost pro čtení a zápis a zdrojový objekt musí být proměnlivý.

Jeden indexer v bezprostředním objektu jako kontext dat

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

key musí být zadaným indexem do slovníku nebo tabulky hash nebo celočíselného indexu pole. Hodnota klíče musí být také typ, který je přímo vázán na vlastnost, kde je použita. Například hash tabulka, která obsahuje řetězcové klíče a řetězcové hodnoty, lze použít tímto způsobem k vytvoření vazby na text pro .TextBox Nebo pokud klíč odkazuje na kolekci nebo podindex, můžete tuto syntaxi použít k vytvoření vazby na cílovou vlastnost kolekce. V opačném případě je nutné odkazovat na konkrétní vlastnost prostřednictvím syntaxe, například <Binding Path="[key].propertyName" .../>.

V případě potřeby můžete zadat typ indexu. Podrobnosti o tomto aspektu cesty indexované vlastnosti naleznete v tématu Binding.Path.

Více vlastností (cílení na nepřímé vlastnosti)

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

propertyName musí být přeložena jako název vlastnosti, která je aktuální DataContext. Vlastnosti propertyName cesty a propertyName2 mohou být všechny vlastnosti, které existují v relaci, kde propertyName2 je vlastnost, která existuje u typu, který je hodnotou propertyName.

Jedna vlastnost, připojená nebo jinak kvalifikovaná typ

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

Závorky označují, že tato vlastnost by PropertyPath měla být vytvořena pomocí částečné kvalifikace. K vyhledání typu s odpovídajícím mapováním může použít obor názvů XML. Vyhledá ownerType typy, ke kterým má procesor XAML přístup prostřednictvím XmlnsDefinitionAttribute deklarací v jednotlivých sestaveních. Většina aplikací má výchozí obor názvů XML namapovaný na http://schemas.microsoft.com/winfx/2006/xaml/presentation obor názvů, takže předpona je obvykle nezbytná pouze pro vlastní typy nebo typy jinak mimo tento obor názvů. propertyName musí být přeložena tak, aby byla název vlastnosti existující v objektu ownerType. Tato syntaxe se obvykle používá pro jeden z následujících případů:

Cesta je zadána v xaml, která je ve stylu nebo šabloně, která nemá zadaný cílový typ. Kvalifikované použití je obecně neplatné pro jiné případy, než je tento, protože v jiných než stylech, ne-šablony případy, vlastnost existuje v instanci, nikoli typu.
Vlastnost je připojená vlastnost.
Vytváříte vazbu na statickou vlastnost.

Pro použití jako cíl scénáře, vlastnost určená jako propertyName musí být DependencyProperty.

Procházení zdroje (vazba k hierarchiím kolekcí)

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

Funkce / v této syntaxi slouží k navigaci v hierarchickém objektu zdroje dat a podporuje se několik kroků v hierarchii s následnými a znaky. Zdrojové účty procházení pro aktuální pozici ukazatele záznamu, která je určena synchronizací dat s uživatelským rozhraním jeho zobrazení. Podrobnosti o vazbě s hierarchickými objekty zdroje dat a koncept ukazatele aktuálního záznamu v datové vazbě najdete v tématu Použití vzoru master-detail s hierarchickými daty nebo přehledem datových vazeb.

Poznámka:

Povrchně se tato syntaxe podobá XPathu. Skutečný výraz XPath pro vazbu ke zdroji dat XML se nepoužívá jako Path hodnota a měl by být použit pro vzájemně se vylučující XPath vlastnost.

Zobrazení kolekcí

Pokud chcete odkazovat na pojmenované zobrazení kolekce, předpona názvu zobrazení kolekce znakem hash (#).

Ukazatel aktuálního záznamu

Pokud chcete odkazovat na aktuální ukazatel záznamu pro zobrazení kolekce nebo scénář vazby hlavních podrobností podrobností, spusťte řetězec cesty lomítkem (/). Jakákoli cesta za lomítkem se prochází od aktuálního ukazatele záznamu.

Více indexerů

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

nebo

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

Pokud daný objekt podporuje více indexerů, lze tyto indexery zadat v uvedeném pořadí, podobně jako syntaxe odkazující na pole. Daný objekt může být buď aktuální kontext, nebo hodnota vlastnosti, která obsahuje více indexového objektu.

Ve výchozím nastavení jsou hodnoty indexeru zadány pomocí charakteristik základního objektu. V případě potřeby můžete zadat typ indexu. Podrobnosti o zadávání indexerů najdete v tématu Binding.Path.

Kombinování syntaxí

Každá z výše uvedených syntaxí může být interspersována. Například následující příklad vytvoří cestu vlastnosti k barvě v určitém x,y ColorGrid vlastnosti, která obsahuje pole SolidColorBrush mřížky pixelů objektů:

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

Řídicí znaky pro řetězce cest vlastností

U určitých obchodních objektů můžete narazit na případ, kdy řetězec cesty k vlastnosti vyžaduje řídicí sekvenci, aby bylo možné správně analyzovat. Nutnost řídicího znaku by měla být vzácná, protože mnoho z těchto znaků má podobné problémy s interakcí s pojmenováním v jazycích, které by se obvykle používaly k definování obchodního objektu.

Uvnitř indexerů ([ ]) znak stříšky (^) uvozuje další znak.
Je nutné uvést (pomocí entit XML) určité znaky, které jsou speciální pro definici jazyka XML. Slouží & k řídicímu znaku "&". Slouží > k úniku koncové značky ">".
Pro zpracování rozšíření značek je nutné řídicí znaky (pomocí zpětného lomítka \), které jsou speciální pro chování analyzátoru WPF XAML.
- Zpětné lomítko (\) je samotný řídicí znak.
- Symbol rovná se (=) odděluje název vlastnosti od hodnoty vlastnosti.
- Čárka (,) odděluje vlastnosti.
- Pravá složená závorka (}) je konec rozšíření značek.

Poznámka:

Technicky vzato tyto řídicí znaky fungují také pro cestu vlastností scénáře, ale obvykle procházíte objektové modely pro existující objekty WPF a únik by měl být zbytečný.

PropertyPath pro cíle animací

Cílovou vlastností animace musí být vlastnost závislosti, která přebírá buď Freezable primitivní typ. Cílová vlastnost typu a případná animovaná vlastnost však může existovat na různých objektech. V případě animací se cesta vlastnosti používá k definování propojení mezi pojmenovanou animační vlastností cílového objektu a zamýšlenou cílovou animační vlastností procházením relací vlastností objektu v hodnotách vlastností.

Obecné aspekty vlastností objektu pro animace

Další informace o konceptech animací obecně najdete v tématu Přehled scénářů a Přehled animací.

Typ hodnoty nebo animovaná vlastnost musí být Freezable buď typ, nebo primitivní. Vlastnost, která spouští cestu, se musí přeložit na název vlastnosti závislosti, která existuje v zadaném TargetName typu.

Aby bylo možné podporovat klonování pro animaci Freezable již zablokovaného objektu, musí být objekt určený TargetName třídou nebo FrameworkElement odvozenou FrameworkContentElement třídou.

Jedna vlastnost cílového objektu

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

propertyName musí být přeložena jako název vlastnosti závislosti, která existuje v zadaném TargetName typu.

Cílení nepřímých vlastností

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

propertyName musí být vlastnost, která je buď Freezable typ hodnoty, nebo primitivní, který existuje u zadaného TargetName typu.

propertyName2 musí být název vlastnosti závislosti, která existuje u objektu, který je hodnotou propertyName. Jinými slovy, propertyName2 musí existovat jako vlastnost závislosti na typu, který je .propertyNamePropertyType

Nepřímé cílení animací je nezbytné kvůli použitým stylům a šablonám. Chcete-li cílit na animaci, potřebujete TargetName na cílový objekt a tento název je vytvořen x :Name nebo Name. I když šablony a prvky stylu mohou mít také názvy, tyto názvy jsou platné pouze v názvovém rozsahu stylu a šablony. (Pokud šablony a styly sdílely názvové rozsahy s kódem aplikace, názvy nemohly být jedinečné. Styly a šablony jsou doslova sdíleny mezi instancemi a trvaly by duplicitní názvy.) Pokud tedy jednotlivé vlastnosti prvku, který chcete animovat, pochází ze stylu nebo šablony, musíte začít s pojmenovanou instancí elementu, která není ze šablony stylu, a pak cílit do vizuálního stromu stylu nebo šablony tak, aby přišla na vlastnost, kterou chcete animovat.

Vlastnost objektu je například Background úplná Panel (ve skutečnosti Brusha) z šablony motivu.SolidColorBrush Aby bylo možné animovat Brush zcela, museli byste být BrushAnimation (pravděpodobně jeden pro každý Brush typ) a neexistuje takový typ. Pokud chcete animovat štětec, nemusíte animovat vlastnosti určitého Brush typu. Musíte se dostat od SolidColorBrush jeho Color k jeho použití ColorAnimation tam. Cesta vlastnosti pro tento příklad by byla Background.Color.

Přidružené vlastnosti

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

Závorky označují, že tato vlastnost by PropertyPath měla být vytvořena pomocí částečné kvalifikace. K vyhledání typu může použít obor názvů XML. Vyhledá ownerType typy, ke kterým má procesor XAML přístup prostřednictvím XmlnsDefinitionAttribute deklarací v jednotlivých sestaveních. Většina aplikací má výchozí obor názvů XML namapovaný na http://schemas.microsoft.com/winfx/2006/xaml/presentation obor názvů, takže předpona je obvykle nezbytná pouze pro vlastní typy nebo typy jinak mimo tento obor názvů. propertyName musí být přeložena tak, aby byla název vlastnosti existující v objektu ownerType. Vlastnost zadaná jako propertyName musí být .DependencyProperty (Všechny připojené vlastnosti WPF se implementují jako vlastnosti závislosti, takže se tento problém týká pouze vlastních připojených vlastností.)

Indexery

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

Většina vlastností nebo Freezable typů závislostí nepodporuje indexer. Proto jediné použití indexeru v animační cestě je na přechodné pozici mezi vlastností, která spouští řetěz na pojmenovaném cíli a případnou animovanou vlastnost. V zadané syntaxi je to propertyName2. Například použití indexeru může být nezbytné, pokud je zprostředkující vlastnost kolekce, jako TransformGroupje například , v cestě k vlastnosti, například RenderTransform.Children[1].Angle.

PropertyPath v kódu

Použití kódu pro PropertyPath, včetně postupu sestavení PropertyPath, je zdokumentované v referenčním tématu pro PropertyPath.

Obecně je navržená tak, PropertyPath aby používala dva různé konstruktory, jeden pro použití vazeb a nejjednodušší použití animací a jeden pro složité použití animací. PropertyPath(Object) Podpis použijte pro použití vazby, kde objekt je řetězec. PropertyPath(Object) Podpis použijte pro cesty animace s jedním krokem, kde objekt je DependencyProperty. PropertyPath(String, Object[]) Podpis použijte pro složité animace. Tento druhý konstruktor používá řetězec tokenu pro první parametr a pole objektů, které vyplňují pozice v řetězci tokenu k definování relace cesty vlastnosti.

Sdílet prostřednictvím