XAML-témaerőforrások

Az XAML témaerőforrásai olyan erőforrások, amelyek különböző értékeket alkalmaznak attól függően, hogy melyik rendszertéma aktív. Az XAML-keretrendszer 3 témát támogat: "Light", "Dark" és "HighContrast".

Előfeltételek: Ez a témakör feltételezi, hogy elolvasta a ResourceDictionary és az XAML erőforráshivatkozásokat.

Témaerőforrások v. statikus erőforrások

Két XAML-korrektúrakiterjesztés hivatkozhat egy XAML-erőforrásra egy meglévő XAML-erőforrásszótárból: {StaticResource} korrektúrakiterjesztés és {ThemeResource} korrektúrakiterjesztés.

A (z) {ThemeResource} korrektúrabővítmény kiértékelése akkor történik, amikor az alkalmazás betöltődik, majd ezt követően minden alkalommal, amikor a téma futásidőben megváltozik. Ez általában annak az eredménye, hogy a felhasználó módosítja az eszköz beállításait, vagy egy programozott módosítást az alkalmazáson belül, amely módosítja az aktuális témát.

Ezzel szemben a {StaticResource} korrektúrakiterjesztés csak akkor lesz kiértékelve, ha az alkalmazás először betölti az XAML-t. Nem frissül. Hasonlóan az XAML-ben található keres és cserél művelethez, amely az alkalmazás indításakor az aktuális futásidejű értékre cserél.

Témaerőforrások az erőforrás-szótár szerkezetében

Minden témaerőforrás az XAML-fájl themeresources.xaml része. Tervezés céljából a themeresources.xaml elérhető a \(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic mappában egy Windows Software Development Kit (SDK) telepítéséből. A themeresources.xaml erőforrásszótárait a generic.xaml is reprodukálja ugyanabban a könyvtárban.

A Windows-futtatókörnyezet nem használja ezeket a fizikai fájlokat futásidejű kereséshez. Ezért vannak kifejezetten egy DesignTime-mappában, és alapértelmezés szerint nem lesznek átmásolva az alkalmazásokba. Ehelyett ezek az erőforrás-szótárak a Windows-futtatókörnyezet részeként léteznek a memóriában, és az alkalmazás XAML-erőforrás-hivatkozásai a téma- vagy rendszererőforrásokra futásidőben oldódnak fel.

Egyéni témaerőforrásokra vonatkozó irányelvek

Kövesse az alábbi irányelveket, amikor saját egyéni témaerőforrásokat határoz meg és használ fel:

A "HighContrast" szótár mellett adja meg a "Világos" és a "Sötét" szótárakat is. Bár létrehozhat egy ResourceDictionary-t "Default" (Alapértelmezett) névvel, célszerűbb egyértelműen megnevezni, és helyette a "Világos", a "Sötét" vagy a "Kontrasztos" elnevezést használni.
Használja a {ThemeResource} korrektúrakiterjesztést a következő helyen: Stílusok, Beállításkezelők, Vezérlősablonok, Tulajdonsághalmazok és Animációk.
Ne használja a {ThemeResource} korrektúrakiterjesztést az erőforrásdefiníciókban a ThemeDictionariesben. Használja helyette a {StaticResource} korrektúrakiterjesztést .

KIVÉTEL: A {ThemeResource} jelölőbővítmény használatával hivatkozhat olyan erőforrásokra, amelyek a ThemeDictionaries alkalmazástémája számára agnosztikusak. Ilyen erőforrások például a hangsúlyos színerőforrások, például SystemAccentColora rendszer színerőforrásai, amelyek általában a "SystemColor" SystemColorButtonFaceColorelőtaggal vannak elnevezve.

Caution

Ha nem követi ezeket az irányelveket, előfordulhat, hogy az alkalmazás témáihoz kapcsolódó váratlan viselkedés jelenik meg. További információ: Hibaelhárítási témaerőforrások szakasz.

Az XAML színrámpa és a témafüggő ecsetek

A "Világos", a "Sötét" és a "HighContrast" témák együttes színkészlete alkotja a Windows színrámpát az XAML-ben. Akár módosítani szeretné a rendszertémákat, akár a saját XAML-elemeire szeretne témát alkalmazni, fontos tisztában lenni a színerőforrások struktúrájával.

A szín Windows app való alkalmazásával kapcsolatos további információkért lásd: Color a Windows-alkalmazásokban.

Világos és sötét színösszeállítás

Az XAML-keretrendszer a "Világos" és a "Sötét" témákhoz szabott értékekkel rendelkező, elnevezett Color-erőforrások készletét biztosítja. WinUI esetén a témaerőforrások a Common theme resources Xaml fájlban vannak definiálva. A színnevek nagyon leíró jellegűek a kívánt használatukhoz, és minden színerőforráshoz tartozik egy megfelelő SolidColorBrush-erőforrás.

Jótanács

A színek vizuális áttekintéséért tekintse meg a WinUI 3 Katalógus alkalmazást: Színek

A WinUI 3 Katalógus alkalmazás interaktív példákat tartalmaz a legtöbb WinUI-vezérlőre, funkcióra és funkcióra. Az alkalmazás lekérése a Microsoft Áruházból vagy a forráskód lekérése GitHub

Windows rendszer kontraszt témaszínei

Az XAML-keretrendszer által biztosított erőforrások mellett a Windows rendszerpalettájából származó színértékek is vannak. Ezek a színek nem a Windows-futtatókörnyezet vagy a Windows-alkalmazásokra vonatkoznak. Az XAML Brush-erőforrások nagy része azonban ezeket a színeket használja, amikor a rendszer működik (és az alkalmazás fut) a "HighContrast" téma használatával. Az XAML-keretrendszer ezeket a rendszerszintű színeket kulcsfontosságú erőforrásokként biztosítja. A kulcsok az elnevezési formátumot követik: SystemColor[name]Color.

A kontrasztos témák támogatásáról további információt a Kontraszt témák című témakörben talál.

Rendszer kiemelő szín

A rendszerkontraszt témaszínek mellett a rendszer hangsúlyszíne speciális színerőforrásként is elérhető a kulccsal SystemAccentColor. Futásidőben ez az erőforrás a Windows személyre szabási beállításaiban a felhasználó által jelölőszínként megadott színt kapja.

Megjegyzés:

Bár felül lehet bírálni a rendszer színerőforrásait, ajánlott tiszteletben tartani a felhasználó színbeállításait, különösen a kontraszttémák beállításainál.

Témafüggő ecsetek

Az előző szakaszokban látható színerőforrások a SolidColorBrush-erőforrások Szín tulajdonságának beállítására szolgálnak a rendszertémakörök erőforrás-szótáraiban. Az ecseterőforrások használatával alkalmazhatja a színt az XAML-elemekre.

Nézzük meg, hogyan határozható meg az ecset színértéke futásidőben. A "Világos" és "Sötét" erőforrásszótárakban ez az ecset a következőképpen van definiálva:

<SolidColorBrush x:Key="TextFillColorPrimaryBrush" Color="{StaticResource TextFillColorPrimary}"/>

A "HighContrast" erőforrásszótárban ez az ecset a következőképpen van definiálva:

<SolidColorBrush x:Key="TextFillColorPrimaryBrush" Color="{ThemeResource SystemColorWindowTextColor}"/>

Ha ezt az kefét XAML-elemre alkalmazza, annak színét futásidőben határozza meg az aktuális téma, ahogyan az ebben a táblázatban látható.

Theme	Színerőforrás	Futásidejű érték
Light	TextFillColorPrimary	#E4000000
Sötét	TextFillColorPrimary	#FFFFFFFF
HighContrast	SystemColorWindowTextColor	A Szöveg beállításban megadott szín.

Az XAML típusú rámpa

A themeresources.xaml fájl több olyan erőforrást határoz meg, amelyek a felhasználói felületen lévő szövegtárolókra alkalmazható stílust határoznak meg, különösen a TextBlock vagy a RichTextBlock esetében. Ezek nem az alapértelmezett implicit stílusok. Ezek segítségével egyszerűbben hozhat létre olyan XAML felhasználói felületi definíciókat, amelyek megfelelnek a Betűtípusok irányelvei című témakörben dokumentált Windows-típus-rámpának.

Ezek a stílusok olyan szövegattribútumokhoz tartoznak, amelyeket a teljes szövegtárolóra szeretne alkalmazni. Ha csak a szöveg szakaszaira szeretne stílusokat alkalmazni, állítsa be az attribútumokat a tárolóban lévő szövegelemeken, például a TextBlock.Inlines-ban való futtatáskor vagy a RichTextBlock.Blocks egy bekezdésén.

A stílusok így néznek ki a TextBlockra alkalmazva:

szövegblokkstílusok

Stílus	Weight	Méret
Felirat	Rendszeres	12
Test	Rendszeres	14
Test erős	Félbold	14
Törzs nagy	Rendszeres	18
Test nagy és erős	Félbold	18
Felirat	Félbold	20
Cím	Félbold	28
Cím nagy	Félbold	40
Display	Félbold	68

<TextBlock Text="Caption" Style="{StaticResource CaptionTextBlockStyle}"/>
<TextBlock Text="Body" Style="{StaticResource BodyTextBlockStyle}"/>
<TextBlock Text="Body Strong" Style="{StaticResource BodyStrongTextBlockStyle}"/>
<TextBlock Text="Body Large" Style="{StaticResource BodyLargeTextBlockStyle}"/>
<TextBlock Text="Body Large Strong" Style="{StaticResource BodyLargeStrongTextBlockStyle}"/>
<TextBlock Text="Subtitle" Style="{StaticResource SubtitleTextBlockStyle}"/>
<TextBlock Text="Title" Style="{StaticResource TitleTextBlockStyle}"/>
<TextBlock Text="Title Large" Style="{StaticResource TitleLargeTextBlockStyle}"/>
<TextBlock Text="Display" Style="{StaticResource DisplayTextBlockStyle}"/>

A Windows típusú rámpa alkalmazásbeli használatáról további információt a Windows-alkalmazások tipográfiája című témakörben talál.

Az XAML-stílusok részleteiért lásd a WinUI-t a GitHub:

Jótanács

A stílusok vizuális áttekintéséért tekintse meg a WinUI 3 Katalógus alkalmazást: Tipográfia

BaseRichTextBlockStyle

TargetType: RichTextBlock

Az összes többi RichTextBlock-tárolóstílus közös tulajdonságait adja meg.

<!-- Usage -->
<RichTextBlock Style="{StaticResource BaseRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BaseRichTextBlockStyle" TargetType="RichTextBlock">
    <Setter Property="FontFamily" Value="Segoe UI Variable"/>
    <Setter Property="FontWeight" Value="SemiBold"/>
    <Setter Property="FontSize" Value="14"/>
    <Setter Property="TextTrimming" Value="None"/>
    <Setter Property="TextWrapping" Value="Wrap"/>
    <Setter Property="LineStackingStrategy" Value="MaxHeight"/>
    <Setter Property="TextLineBounds" Value="Full"/>
    <Setter Property="OpticalMarginAlignment" Value="TrimSideBearings"/>
</Style>

BodyRichTextBlockStyle

<!-- Usage -->
<RichTextBlock Style="{StaticResource BodyRichTextBlockStyle}">
    <Paragraph>Rich text.</Paragraph>
</RichTextBlock>

<!-- Style definition -->
<Style x:Key="BodyRichTextBlockStyle" TargetType="RichTextBlock" BasedOn="{StaticResource BaseRichTextBlockStyle}">
    <Setter Property="FontWeight" Value="Normal"/>
</Style>

Megjegyzés: A RichTextBlock stílusok nem rendelkeznek a TextBlock által használt összes szövegrészstílussal, főként azért, mert a RichTextBlock blokkalapú dokumentumobjektum-modellje megkönnyíti az attribútumok beállítását az egyes szövegelemeken. A TextBlock.Text XAML tartalomtulajdonság használatával való beállítása olyan helyzetet is eredményez, amikor nincs stíluselem, ezért a tárolót kell stílusba állítania. Ez nem jelent problémát a RichTextBlock esetében, mert a szöveges tartalomnak mindig adott szöveges elemekben kell lennie, például a Bekezdésben, ahol XAML-stílusokat alkalmazhat az oldalfejléchez, az oldal alfejlécéhez és a hasonló szövegrész-definíciókhoz.

Egyéb elnevezett stílusok

Van egy további készlet kulcsos stílus definíció, amelyet alkalmazhat, hogy egy Gomb stílusát másképp alakítsa az alapértelmezett implicit stílusához képest.

NavigationBackButtonNormalStyle

TargetType: Button

Ez a stílus egy teljes sablont biztosít egy gombhoz , amely egy navigációs alkalmazás navigációs vissza gombja lehet. Az alapértelmezett méret 40 x 40 képpont. A stílus testreszabásához explicit módon beállíthatja a Gomb magasságát, szélességét, Betűméretét és egyéb tulajdonságait, vagy létrehozhat egy származtatott stílust a BasedOn használatával.

Íme egy gomb , amelyen a NavigationBackButtonNormalStyle erőforrás van alkalmazva.

<Button Style="{StaticResource NavigationBackButtonNormalStyle}" />

A következőképpen néz ki:

NavigationBackButtonSmallStyle

TargetType: Button

Ez a stílus egy teljes sablont biztosít egy gombhoz , amely egy navigációs alkalmazás navigációs vissza gombja lehet. Hasonló a NavigationBackButtonNormalStyle-hoz, de mérete 30 x 30 képpont.

Íme egy gomb , amelyen a NavigationBackButtonSmallStyle erőforrás van alkalmazva.

<Button Style="{StaticResource NavigationBackButtonSmallStyle}" />

Témaerőforrások hibaelhárítása

Ha nem követi a témaerőforrások használatára vonatkozó irányelveket, előfordulhat, hogy váratlan viselkedés jelenik meg az alkalmazásban lévő témákkal kapcsolatban.

Ha például világos témájú legördülő panelt nyit meg, a sötét témájú alkalmazás részei is megváltoznak, mintha világos témában lennének. Vagy ha egy világos témájú lapra lép, majd vissza lép, az eredeti sötét témájú oldal (vagy annak részei) most úgy néz ki, mintha a világos témában lenne.

Az ilyen típusú problémák általában akkor fordulnak elő, ha egy "Alapértelmezett" témát és egy "HighContrast" témát ad meg a kontrasztos forgatókönyvek támogatásához, majd a "Világos" és a "Sötét" témákat is használhatja az alkalmazás különböző részeiben.

Vegyük például ezt a téma szótár definíciót:

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Intuitív módon ez helyesnek tűnik. Meg szeretné változtatni a nagy kontrasztú módban mutatott myBrush színt, de ha nem nagy kontrasztú módban van, akkor a {ThemeResource} jelölőnyelvi kiterjesztésre támaszkodva győződjön meg arról, hogy myBrush az ön témájának megfelelő színére mutat. Ha az alkalmazás nem rendelkezik FrameworkElement.RequestedTheme beállítással a vizualizációfán belüli elemekre, ez általában a várt módon működik. Az alkalmazásban azonban problémákba ütközik, amint elkezdi újraémázni a vizualizációfa különböző részeit.

Azért merül fel a probléma, mert az ecsetek megosztott erőforrások, ellentétben a legtöbb más XAML-típussal. Ha az XAML alfáiban 2 olyan elem található, amelyek különböző témákkal hivatkoznak ugyanarra az ecseterőforrásra, akkor amikor a keretrendszer végigvezeti az egyes alfákat a {ThemeResource} korrektúrakiterjesztési kifejezéseinek frissítéséhez, a megosztott ecseterőforrás módosításai megjelennek a másik alfán, ami nem a kívánt eredmény.

Ennek kijavításához cserélje le az "Alapértelmezett" szótárat külön témaszótárakra a "Világos" és a "Sötét" témákhoz a "HighContrast" mellett:

<!-- DO NOT USE. THIS XAML DEMONSTRATES AN ERROR. -->
<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

A problémák azonban továbbra is fennállnak, ha ezekre az erőforrásokra olyan öröklődő tulajdonságok hivatkoznak, mint az Előtér. Előfordulhat, hogy az egyéni vezérlősablon egy elem előtérszínét adja meg a {ThemeResource} korrektúrakiterjesztés használatával, de amikor a keretrendszer az örökölt értéket gyermekelemekre propagálja, közvetlen hivatkozást biztosít arra az erőforrásra, amelyet a {ThemeResource} korrektúrakiterjesztési kifejezés feloldott. Ez problémákat okoz, ha a keretrendszer a vezérlő vizualizációfáját követve módosítja a témát. Újra kiértékeli a {ThemeResource} jelölőkiterjesztési kifejezést egy új ecseterőforrás beszerzéséhez, de még nem terjeszti ki ezt a hivatkozást a vezérlő gyermekeire; ez később történik, például a következő mérési ciklus során.

Ennek eredményeképpen, miután a vezérlő vizualizációfáját egy témamódosításra válaszul sétáltatták, a keretrendszer végigvezeti a gyermekeket, és frissíti a rajtuk beállított {ThemeResource} korrektúrakiterjesztési kifejezéseket vagy a tulajdonságokon beállított objektumokat. Itt jelentkezik a probléma; a keretrendszer feldolgozza az ecset erőforrást, és mivel a színét {ThemeResource} jelölőkiterjesztéssel határozza meg, újra kiértékeli.

Jelenleg úgy tűnik, hogy a keretrendszer szennyezte a témaszótárat, mert most már rendelkezik egy erőforrással az egyik szótárból, amelynek színkészlete egy másik szótárból származik.

A probléma megoldásához használja a {StaticResource} korrektúrabővítményt a {ThemeResource} korrektúrakiterjesztés helyett. Az irányelvek alkalmazásával a témaszótárak a következőképpen néznek ki:

<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <SolidColorBrush x:Key="myBrush" Color="{StaticResource ControlFillColorDefault}"/>
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <SolidColorBrush x:Key="myBrush" Color="{ThemeResource SystemColorButtonFaceColor}"/>
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Figyelje meg, hogy a (z) {ThemeResource} korrektúrakiterjesztés továbbra is a "HighContrast" szótárban van használatban a {StaticResource} korrektúrakiterjesztés helyett. Ez a helyzet az iránymutatásokban korábban megadott kivétel alá tartozik. A "HighContrast" témához használt ecsetértékek többsége olyan színválasztékokat használ, amelyeket a rendszer globálisan szabályoz, de az XAML számára speciálisan elnevezett erőforrásként (a névben a "SystemColor" előtaggal vannak elérhetővé téve). A rendszer lehetővé teszi a felhasználó számára, hogy az Egyszerűség Access központban állítsa be a kontraszttéma beállításaihoz használni kívánt színeket. Ezek a színválasztások a speciálisan elnevezett erőforrásokra lesznek alkalmazva. Az XAML-keretrendszer ugyanazt a témát módosító eseményt használja a kefék frissítéséhez, amikor azt észleli, hogy a rendszer szintjén megváltoztak. Ezért használja itt a {ThemeResource} korrektúrakiterjesztést.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-07-27