Dela via

{ThemeResource} markup-tillägg

Ger ett värde för alla XAML-attribut genom att utvärdera en referens till en resurs, med ytterligare systemlogik som hämtar olika resurser beroende på det aktuella aktiva temat. På samma sätt som {StaticResource}-markeringstillägget definieras resurser i en ResourceDictionary och en ThemeResource-användning refererar till nyckeln för resursen i ResourceDictionary.

XAML-attributanvändning

<object property="{ThemeResource key}" .../>

XAML-värden

Begrepp Description
key Nyckeln för den begärda resursen. Den här nyckeln tilldelas ursprungligen av ResourceDictionary. En resursnyckel kan vara valfri sträng som definieras i XamlName-grammatiken.

Anmärkningar

En ThemeResource är en teknik för att hämta värden för ett XAML-attribut som definieras någon annanstans i en XAML-resursordlista. Markeringstillägget har samma grundläggande syfte som markeringstillägget {StaticResource}. Skillnaden i beteende jämfört med {StaticResource} markeringstillägg är att en ThemeResource-referens dynamiskt kan använda olika ordlistor som den primära uppslagsplatsen, beroende på vilket tema som för närvarande används av systemet.

När appen först startar utvärderas alla resursreferenser som görs av en ThemeResource-referens baserat på det tema som används vid start. Men om användaren senare ändrar det aktiva temat vid körning utvärderar systemet varje ThemeResource-referens på nytt, hämtar en temaspecifik resurs som kan vara annorlunda och redisplayar appen med nya resursvärden på alla lämpliga platser i det visuella trädet. En StaticResource bestäms vid XAML-inläsningstid eller appstart och utvärderas inte på nytt vid körning. (Det finns andra tekniker som visuella tillstånd som läser in XAML dynamiskt, men dessa tekniker fungerar på en högre nivå än den grundläggande resursutvärdering som aktiveras av {StaticResource}-markeringstillägget).

ThemeResource tar ett argument som anger nyckeln för den begärda resursen. En resursnyckel är alltid en sträng i Windows Runtime XAML. Mer information om hur resursnyckeln ursprungligen anges finns i x:Key-attribut.

Mer information om hur du definierar resurser och korrekt använder en ResourceDictionary, inklusive exempelkod, finns i ResourceDictionary- och XAML-resursreferenser.

Viktig Precis som med StaticResource får en ThemeResource inte försöka göra en vidarereferens till en resurs som definieras lexikalt ytterligare i XAML-filen. Försök att göra det stöds inte. Även om en framåtreferens inte misslyckas, medför försök att göra en en prestandapåföljd. För bästa resultat justerar du sammansättningen av dina resursordlistor så att framåtreferenser undviks.

Försök att ange ett ThemeResource till en nyckel som inte kan matcha genererar ett XAML-parsningsfel vid körning. Designverktyg kan också erbjuda varningar eller fel.

I Windows Runtime XAML-processorimplementeringen finns det ingen stödklassrepresentation för ThemeResource. Den närmaste motsvarigheten i kod är att använda samlings-API:et för en ResourceDictionary, till exempel att anropa Contains eller *TryGetValue.

ThemeResource är ett tillägg för markering. Markeringstillägg implementeras vanligtvis när det finns ett krav på att escape-attributvärden ska vara andra än literalvärden eller hanterarnamn, och kravet är mer globalt än att bara placera typkonverterare på vissa typer eller egenskaper. Alla markeringstillägg i XAML använder tecknen "{" och "}" i attributsyntaxen, vilket är den konvention genom vilken en XAML-processor känner igen att ett markeringstillägg måste bearbeta attributet.

När och hur du använder {ThemeResource} i stället för {StaticResource}

De regler genom vilka en ThemeResource löses upp till ett objekt i en resursordbok är generellt desamma som StaticResource. En ThemeResource-sökning kan utökas till ResourceDictionary-filerna som refereras i en ThemeDictionaries-samling , men en StaticResource kan också göra det. Skillnaden är att en ThemeResource kan utvärderas igen vid körning och att en StaticResource inte kan göra det.

Uppsättningen med nycklar i varje temaordlista ska ge samma uppsättning nyckelade resurser oavsett vilket tema som är aktivt. Om det finns en viss nyckelresurs i temaordlistan HighContrast bör en annan resurs med det namnet också finnas i Ljus och Standard. Om det inte är sant kan resurssökningen misslyckas när användaren byter teman och appen inte ser rätt ut. Det är dock möjligt att en temaordlista kan innehålla nyckelade resurser som endast refereras inifrån samma omfång för att tillhandahålla undervärden. dessa behöver inte vara likvärdiga i alla teman.

I allmänhet bör du placera resurser i temaordlistor och göra referenser till dessa resurser med hjälp av ThemeResource endast när dessa värden kan ändras mellan teman eller stöds av värden som ändras. Detta är lämpligt för den här typen av resurser:

  • Penslar, i synnerhet färger för SolidColorBrush. Dessa utgör cirka 80% av ThemeResource-användningarna i XAML-standardkontrollmallarna (generic.xaml).
  • Pixelvärden för kantlinjer, förskjutningar, marginal och utfyllnad och så vidare.
  • Teckensnittsegenskaper som FontFamily eller FontSize.
  • Slutför mallar för ett begränsat antal kontroller som vanligtvis är systemformat och används för dynamisk presentation, till exempel GridViewItem och ListViewItem.
  • Textvisningsformat (vanligtvis för att ändra teckenfärg, bakgrund och eventuellt storlek).

Windows Runtime innehåller en uppsättning resurser som är specifikt avsedda att refereras till av ThemeResource. Alla dessa visas som en del av XAML-filen themeresources.xaml, som finns i mappen include/winrt/xaml/design som en del av Windows Software Development Kit (SDK). Dokumentation om temapenslar och ytterligare formatmallar som definieras i themeresources.xaml finns i XAML-temaresurser. Penslar dokumenteras i en tabell som anger vilket färgvärde varje pensel har för vart och ett av de tre möjliga aktiva temana.

XAML-definitionerna för visuella tillstånd i en kontrollmall bör använda ThemeResource-referenser när det finns en underliggande resurs som kan ändras på grund av en temaändring. En ändring av systemtema orsakar vanligtvis inte heller en ändring av det visuella tillståndet. Resurserna måste använda ThemeResource-referenser i det här fallet så att värden kan utvärderas på nytt för det fortfarande aktiva visuella tillståndet. Om du till exempel har ett visuellt tillstånd som ändrar en penselfärg för en viss användargränssnittsdel och en av dess egenskaper, och den penselfärgen skiljer sig åt per tema, bör du använda en ThemeResource-referens för att ange egenskapens värde i standardmallen och även eventuella ändringar av det visuella tillståndet i standardmallen.

ThemeResource-användning kan ses i en serie beroende värden. Till exempel kan ett färgvärde som används av en SolidColorBrush som också är en nyckelad resurs använda en ThemeResource-referens . Men alla gränssnittsegenskaper som använder den nyckelade SolidColorBrush-resursen skulle också använda en ThemeResource-referens , så att det specifikt är varje egenskap av penseltyp som aktiverar en dynamisk värdeändring när temat ändras.

Notering{ThemeResource} och utvärdering av körningsresurser vid temaväxling stöds i Windows 8.1 XAML men stöds inte i XAML för appar som riktar sig till Windows 8.

Systemresurser

Vissa temaresurser refererar till systemresursvärden som ett underliggande undervärde. En systemresurs är ett särskilt resursvärde som inte finns i någon XAML-resursordlista. Dessa värden förlitar sig på beteendet i Windows Runtime XAML-stöd för att vidarebefordra värden från själva systemet och representera dem i ett formulär som en XAML-resurs kan referera till. Det finns till exempel en systemresurs med namnet "SystemColorButtonFaceColor" som representerar en RGB-färg. Den här färgen kommer från aspekter av systemfärger och teman som inte bara är specifika för Windows Runtime- och Windows Runtime-appar.

Systemresurser är ofta de underliggande värdena för ett tema med hög kontrast. Användaren har kontroll över färgvalen för sitt högkontrasttema och användaren gör dessa val med hjälp av systemfunktioner som inte heller är specifika för Windows Runtime-appar. Genom att referera till systemresurserna som ThemeResource-referenser kan standardbeteendet för högkontrasteman för Windows Runtime-appar använda dessa temaspecifika värden som styrs av användaren och exponeras av systemet. Dessutom markeras referenserna nu för ny utvärdering om systemet identifierar en ändring av ett körtidstema.

Ett exempel på {ThemeResource}-användning

Här är några exempel på XAML som hämtats från standardfilerna generic.xaml och themeresources.xaml för att illustrera hur du använder ThemeResource. Vi tittar bara på en mall ( standardknappen) och hur två egenskaper deklareras (bakgrund och förgrund) för att svara på temaändringar.

    <!-- Default style for Windows.UI.Xaml.Controls.Button -->
    <Style TargetType="Button">
        <Setter Property="Background" Value="{ThemeResource ButtonBackgroundThemeBrush}" />
        <Setter Property="Foreground" Value="{ThemeResource ButtonForegroundThemeBrush}"/>
...

Här tar egenskaperna ett penselvärde och referensen till SolidColorBrush-resurser som heter ButtonBackgroundThemeBrush och ButtonForegroundThemeBrush görs med hjälp av ThemeResource.

Samma egenskaper justeras också av några av de visuella tillstånden för en knapp. I synnerhet ändras bakgrundsfärgen när en knapp klickas. Även här använder animeringarna Background och Foreground i visual state storyboard DiscreteObjectKeyFrame-objekt och referenser till penslar med ThemeResource som nyckelramvärde.

<VisualState x:Name="Pressed">
  <Storyboard>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Border"
        Storyboard.TargetProperty="Background">
      <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedBackgroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter"
         Storyboard.TargetProperty="Foreground">
       <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedForegroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
  </Storyboard>
</VisualState>

Var och en av dessa penslar definieras tidigare i generic.xaml: de måste definieras innan några mallar använder dem för att undvika XAML-vidarereferenser. Här är dessa definitioner för temaordlistan "Standard".

    <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Default">
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="Transparent" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="#FFFFFFFF" />
...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="#FFFFFFFF" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="#FF000000" />
...

Sedan har var och en av de andra temaordlistorna även dessa penslar definierade, till exempel:

        <ResourceDictionary x:Key="HighContrast">
            <!-- High Contrast theme resources -->
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />

...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />

Här är värdet Color en annan ThemeResource-referens till en systemresurs. Om du refererar till en systemresurs och vill att den ska ändras som svar på en temaändring bör du använda ThemeResource för att göra referensen.

Stöd för designtidsverktyg för {ThemeResource}-markupförlängning

Microsoft Visual Studio kan inkludera möjliga nyckelvärden i Microsoft IntelliSense-listrutorna när du använder markeringstillägget {ThemeResource} på en XAML-sida. När du till exempel skriver {ThemeResource visas någon av resursnycklarna från XAML-temaresurserna .

När en resursnyckel finns som en del av {ThemeResource}-användning kan funktionen Gå till definition (F12) lösa resursen och visa dig generic.xaml för designläget, där temaresursen har definierats. Eftersom temaresurser definieras mer än en gång (per tema) går du till Definition och tar dig till den första definitionen som finns i filen, vilket är definitionen för Standard. Om du vill ha de andra definitionerna kan du söka efter nyckelnamnet i filen och hitta de andra temanas definitioner.