Přehled převaděčů typů pro XAML

Článek
10/18/2023

Převaděče typů poskytují logiku pro zapisovač objektů, který převádí z řetězce v kódu XAML na konkrétní objekty v grafu objektu. V .NET XAML Services musí být převaděč typů třída, která je odvozena z TypeConverter. Některé převaděče také podporují cestu pro uložení XAML a lze jej použít k serializaci objektu do řetězcového formuláře v serializaci značek. Toto téma popisuje, jak a kdy jsou vyvolány převaděče typů v XAML a poskytuje rady implementace pro přepsání TypeConvertermetody .

Koncepty převodu typů

Následující části vysvětlují základní koncepty, jak XAML používá řetězce a jak zapisovače objektů ve službách .NET XAML používají převaděče typů ke zpracování některých řetězcových hodnot, které jsou zjištěny ve zdroji XAML.

Hodnoty XAML a řetězce

Když nastavíte hodnotu atributu v souboru XAML, počáteční typ této hodnoty je řetězec v obecném smyslu a hodnota atributu řetězce ve smyslu XML. Dokonce i jiné primitivy, jako Double jsou počáteční řetězce procesoru XAML.

Ve většině případů procesor XAML potřebuje ke zpracování hodnoty atributu dva části informací. První informace je typ hodnoty vlastnosti, která je nastavena. Jakýkoli řetězec, který definuje hodnotu atributu a který je zpracován v XAML, musí být nakonec převeden nebo přeložen na hodnotu tohoto typu. Pokud je hodnota primitivním analyzátorem XAML (například číselnou hodnotou), pokusí se o přímý převod řetězce. Pokud hodnota atributu odkazuje na výčet, zadaný řetězec se zkontroluje, zda se název shoduje s pojmenovanou konstantou v daném výčtu. Pokud hodnota není primitivní nebo konstantní název z výčtu, musí být příslušný typ schopen poskytnout hodnotu nebo odkaz založený na převedeného řetězci.

Poznámka:

Direktivy jazyka XAML nepoužívají převaděče typů.

Převaděče typů a rozšíření značek

Před kontrolou typu vlastnosti a dalších aspektů musí procesor XAML zpracovávat použití rozšíření značek. Pokud například vlastnost, která je nastavena jako atribut obvykle má převod typu, ale v konkrétním případě je nastaven pomocí použití rozšíření značek, pak se nejprve zpracuje chování rozšíření značek. Jednou z běžných situací, kdy je nezbytné rozšíření značek, je vytvořit odkaz na objekt, který již existuje. V tomto scénáři může převaděč bezstavového typu vygenerovat pouze novou instanci, která nemusí být žádoucí. Další informace o rozšířeních značek naleznete v tématu Rozšíření značek pro PŘEHLED XAML.

Převaděče nativních typů

V implementacích služeb WINDOWS Presentation Foundation (WPF) a .NET XAML existují určité typy CLR, které mají nativní zpracování převodu typů. Tyto typy CLR se ale obvykle nemyslí jako primitivy. Příkladem takového typu je DateTime. Jedním z důvodů, proč architektura rozhraní .NET Framework funguje: typ DateTime je definován v knihovně mscorlib, což je nejzásadnější knihovna v .NET. DateTime atribut, který pochází z jiného sestavení, které zavádí závislost (TypeConverterAttribute je ze systému) není povoleno. Proto nelze podporovat obvyklý mechanismus zjišťování převaděče typů přiřazením. Analyzátor XAML má místo toho seznam typů, které potřebují nativní zpracování, a zpracovává tyto typy podobně jako skutečné primitivy. V případě DateTimetohoto zpracování zahrnuje volání Parse.

Implementace převaděče typů

Následující části diskutují o rozhraní API TypeConverter třídy.

TypeConverter

V rámci služeb .NET XAML jsou všechny převaděče typů, které se používají pro účely XAML, třídy odvozené ze základní třídy TypeConverter. Třída TypeConverter existovala ve verzích rozhraní .NET Framework před tím, než existoval XAML. Jedním z původních TypeConverter scénářů bylo poskytnutí převodu řetězců pro editory vlastností ve vizuálních návrhářích.

Pro XAML se role TypeConverter rozbalí. Pro účely TypeConverter XAML je základní třída pro poskytování podpory pro určité převody na řetězec a z řetězců. Z řetězce umožňuje parsovat hodnotu atributu řetězce z XAML. To-string může povolit zpracování hodnoty za běhu konkrétní vlastnosti objektu zpět do atributu XAML pro serializaci.

TypeConverter definuje čtyři členy, které jsou relevantní pro převod na řetězec a z řetězce pro účely zpracování XAML:

Z těchto členů je nejdůležitější metoda ConvertFrom, která převede vstupní řetězec na požadovaný typ objektu. Metodu ConvertFrom lze implementovat pro převod širšího rozsahu typů na zamýšlený cílový typ převaděče. Proto může sloužit účelům, které překračují rámec XAML, jako je podpora převodů za běhu. Pro použití XAML je ale důležitá pouze cesta kódu, která může zpracovat String vstup.

Druhá nejdůležitější metoda je ConvertTo. Pokud je aplikace převedena na reprezentaci značek (například pokud je uložena do XAML jako soubor), ConvertTo je zapojena do většího scénáře zapisovače textu XAML, aby vytvořil reprezentaci značek. V tomto případě je důležitá cesta kódu pro XAML, když volající předá destinationType znak .String

CanConvertTo a CanConvertFrom jsou metody podpory, které se používají, když služba dotazuje schopnosti TypeConverter implementace. Tyto metody je nutné implementovat, aby se vrátily true pro případy specifické pro typ, které ekvivalentní metody převodu vašeho převaděče podporují. Pro účely XAML to obecně znamená String typ.

Jazykové verze a převaděče typů pro XAML

Každá TypeConverter implementace může jedinečně interpretovat, co je platný řetězec pro převod, a může také použít nebo ignorovat popis typu, který je předán jako parametry. Důležitým aspektem pro převod jazykových verzí a typů XAML je následující: přestože použití lokalizovatelných řetězců jako hodnot atributů je podporováno jazykem XAML, nemůžete tyto lokalizovatelné řetězce použít jako vstup převaděče typů s konkrétními požadavky na jazykovou verzi. Toto omezení je způsobeno tím, že převaděče typů pro hodnoty atributů XAML zahrnují nutně chování zpracování XAML v jazyce s pevnou jazykovou verzí, které používá en-US jazykovou verzi. Další informace o důvodech návrhu tohoto omezení najdete v přehledu specifikace jazyka XAML ([MS-XAML]) nebo globalizace a lokalizace WPF.

Jako příklad, kdy může být jazyková verze problémem, používají některé jazykové verze čárku místo tečky jako oddělovač desetinných míst pro čísla ve formě řetězce. Toto použití koliduje s chováním, které má mnoho existujících převaděčů typů, což je použít čárku jako oddělovač. Předání jazykové verze xml:lang v okolním xaml problém nevyřeší.

Implementace funkce ConvertFrom

Aby byla použitelná jako TypeConverter implementace podporující XAML, ConvertFrom musí metoda pro tento převaděč přijmout řetězec jako value parametr. Pokud je řetězec v platném formátu a lze jej převést implementací TypeConverter , vrácený objekt musí podporovat přetypování na typ, který je očekáván vlastností. ConvertFrom V opačném případě musí implementace vrátit null.

Každá TypeConverter implementace může jedinečně interpretovat, co představuje platný řetězec pro převod, a může také použít nebo ignorovat popis typu nebo kontexty jazykové verze, které jsou předány jako parametry. Zpracování WPF XAML však nemusí předávat hodnoty kontextu popisu typu ve všech případech a také nemusí předávat jazykovou verzi na xml:langzákladě .

Poznámka:

Nepoužívejte složené závorky ({}), konkrétně levou složenou závorku ({), jako prvek formátu řetězce. Tyto znaky jsou vyhrazeny jako vstup a konec pro sekvenci rozšíření značek.

Je vhodné vyvolat výjimku v případě, že převaděč typů musí mít přístup ke službě XAML ze zapisovače objektů .NET XAML Services, ale GetService volání, které je provedeno v kontextu nevrací tuto službu.

Implementace metody ConvertTo

ConvertTo je potenciálně používán pro podporu serializace. Podpora serializace pro ConvertTo váš vlastní typ a jeho typ převaděče není absolutní požadavek. Pokud však implementujete ovládací prvek nebo používáte serializaci jako součást funkcí nebo návrhu třídy, měli byste implementovat ConvertTo.

Aby byla použitelná jako TypeConverter implementace podporující XAML, ConvertTo musí metoda tohoto převaděče přijmout instanci typu (nebo hodnoty), která je podporována value jako parametr. destinationType Pokud je parametr typu String, vrácený objekt musí být schopen přetypovat jako String. Vrácený řetězec musí představovat serializovanou hodnotu value. V ideálním případě by formát serializace, který zvolíte, měl být schopen vygenerovat stejnou hodnotu, jako kdyby byl tento řetězec předán implementaci ConvertFrom stejného převaděče, bez významné ztráty informací.

Pokud hodnotu nelze serializovat nebo převaděč nepodporuje serializaci, ConvertTo implementace musí vrátit null a může vyvolat výjimku. Pokud však vyvoláte výjimky, měli byste hlásit neschopnost použít tento převod jako součást vaší CanConvertTo implementace, aby byl podporován osvědčený postup kontroly s CanConvertTo prvním cílem vyhnout se výjimkám.

Pokud parametr destinationType není typu String, můžete zvolit vlastní zpracování převaděče. Obvykle se vrátíte k základnímu zpracování implementace, které v základu ConvertTo vyvolává konkrétní výjimku.

Implementace CanConvertFrom

Vaše CanConvertFrom implementace by se měla vrátit true pro sourceType typ String a jinak se odložit na základní implementaci. Nevyvolávejte výjimky z CanConvertFrom.

Implementace CanConvertTo

Vaše CanConvertTo implementace by se měla vrátit true pro destinationType typ Stringa jinak odložit základní implementaci. Nevyvolávejte výjimky z CanConvertTo.

Použití TypeConverterAttribute

Aby se váš převaděč vlastních typů používal jako převaděč typu pro vlastní třídu pomocí .NET XAML Services, musíte použít definici TypeConverterAttribute třídy. Zadaným ConverterTypeName atributem musí být název typu vašeho vlastního převaděče typů. Pokud tento atribut použijete, když procesor XAML zpracovává hodnoty, ve kterých typ vlastnosti používá váš vlastní typ třídy, může vstupní řetězce a vrátit instance objektů.

Můžete také poskytnout převaděč typů pro jednotlivé vlastnosti. Místo použití TypeConverterAttribute definice třídy ji použijte na definici vlastnosti (hlavní definice, nikoli get/set implementace v ní). Typ vlastnosti se musí shodovat s typem, který je zpracován vaším převaděčem vlastního typu. Při použití tohoto atributu, když procesor XAML zpracovává hodnoty této vlastnosti, může zpracovávat vstupní řetězce a vracet instance objektů. Technika převaděče typů vlastností je užitečná, pokud se rozhodnete použít typ vlastnosti z rozhraní Microsoft .NET Framework nebo z některé jiné knihovny, kde nemůžete řídit definici třídy a nelze ji použít TypeConverterAttribute tam.

Chcete-li zadat chování převodu typu pro vlastní připojený člen, použijte TypeConverterAttribute u Get metody přistupování vzoru implementace připojeného členu.

Přístup k kontextu zprostředkovatele služeb z implementace rozšíření značek

Dostupné služby jsou stejné pro jakýkoli převaděč hodnot. Rozdíl je v tom, jak každý převaděč hodnot přijímá kontext služby. Přístup ke službám a dostupným službám jsou popsané v tématu Převaděče typů a rozšíření značek pro XAML.

Převaděče typů ve streamu uzlu XAML

Pokud pracujete s datovým proudem uzlu XAML, akce nebo konečný výsledek převaděče typů se ještě nespustí. V cestě načtení zůstane řetězec atributu, který se nakonec musí převést na typ, aby bylo možné načíst textovou hodnotu v rámci počátečního člena a koncového člena. Pomocí vlastnosti lze určit XamlMember.TypeConverter převaděč typů, který je nakonec potřebný pro tuto operaci. Nicméně získání platné hodnoty XamlMember.TypeConverter od spoléhá na to, že má kontext schématu XAML, který má přístup k těmto informacím prostřednictvím podkladového členu, nebo typ hodnoty objektu, kterou člen používá. Vyvolání chování převodu typů také vyžaduje kontext schématu XAML, protože vyžaduje mapování typu a vytvoření instance převaděče.