Udostępnij przez

Znacznik rozszerzenia {ThemeResource}

Udostępnia wartość dla dowolnego atrybutu XAML, oceniając odwołanie do zasobu, z dodatkową logiką systemową, która pobiera różne zasoby w zależności od aktualnie aktywnego motywu. Podobnie jak rozszerzenie znaczników {StaticResource}, zasoby są definiowane w słowniku zasobów, a użycie ThemeResource odnosi się do klucza tego zasobu w słowniku zasobów.

Użycie atrybutu XAML

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

Wartości XAML

Termin Description
klucz Klucz zasobu, o który zażądano. Ten klucz jest początkowo przypisywany przez ResourceDictionary. Klucz zasobu może być dowolnym ciągiem zdefiniowanym w gramatyce XamlName.

Uwagi

ThemeResource to technika uzyskiwania wartości atrybutu XAML zdefiniowanego w innym miejscu w słowniku zasobów XAML. Rozszerzenie znacznikowe służy do tego samego podstawowego celu, co rozszerzenie znacznikowe {StaticResource}. Różnica w zachowaniu w przeciwieństwie do rozszerzenia znaczników {StaticResource} polega na tym, że odwołanie ThemeResource może dynamicznie używać różnych słowników jako miejsca podstawowego wyszukiwania, w zależności od tego, który motyw jest obecnie używany przez system.

Gdy aplikacja uruchamia się po raz pierwszy, wszystkie odwołania do zasobów dokonane przez odwołanie ThemeResource są oceniane na podstawie motywu używanego w momencie startu. Jeśli jednak użytkownik zmieni aktywny motyw w czasie wykonywania, system ponownie oceni każde odwołanie ThemeResource, pobierze zasób specyficzny dla motywu, który może być inny, i ponownie wyświetli aplikację z nowymi wartościami zasobów we wszystkich odpowiednich miejscach w drzewie wizualnym. Wartość StaticResource jest określana w czasie ładowania XAML lub przy uruchamianiu aplikacji i nie będzie ponownie oceniana w czasie wykonywania. (Istnieją inne techniki, takie jak stany wizualne, które dynamicznie ładują kod XAML, ale te techniki działają na wyższym poziomie niż ocena podstawowych zasobów włączona przez rozszerzenie znaczników {StaticResource}).

Element ThemeResource przyjmuje jeden argument, który określa klucz żądanego zasobu. Klucz zasobu jest zawsze ciągiem znaków w Windows Runtime XAML. Aby uzyskać więcej informacji na temat sposobu początkowego określenia klucza zasobu, zobacz atrybut x:Key.

Aby uzyskać więcej informacji na temat definiowania zasobów i prawidłowego używania ResourceDictionary, w tym przykładowego kodu, zobacz ResourceDictionary i referencje zasobów XAML.

Ważny Podobnie jak w przypadku usługi StaticResource, element ThemeResource nie może podjąć próby przekazania odwołania do zasobu, który jest zdefiniowany leksycznie dalej w pliku XAML. Próba wykonania tej czynności nie jest obsługiwana. Nawet jeśli odwołanie do przodu nie kończy się niepowodzeniem, próba utworzenia go niesie ze sobą karę za wydajność. Aby uzyskać najlepsze rezultaty, dostosuj układ słowników zasobów, aby uniknąć odwołań w przód.

Próba przypisania ThemeResource do kluczowi, którego nie można rozpoznać, spowoduje wyjątek parsowania XAML w czasie wykonania. Narzędzia projektowe mogą również oferować ostrzeżenia lub błędy.

W implementacji procesora XAML środowiska uruchomieniowego systemu Windows nie ma reprezentacji klasy zapasowej dla themeResource. Najbliższym odpowiednikiem w kodzie jest użycie API kolekcji ResourceDictionary, na przykład wywołania Contains lub TryGetValue.

ThemeResource to rozszerzenie znaczników. Rozszerzenia znaczników są zwykle wdrażane, gdy istnieje potrzeba przetworzenia wartości atrybutów, aby były inne niż wartości dosłowne lub nazwy procedur obsługi lub funkcji, a potrzeba ta jest bardziej globalna niż tylko zastosowanie konwerterów typów do określonych typów lub właściwości. Wszystkie rozszerzenia znaczników w języku XAML używają znaków "{" i "}" w składni atrybutu, która jest konwencją, zgodnie z którą procesor XAML rozpoznaje, że rozszerzenie znaczników musi przetworzyć atrybut.

Kiedy i jak używać elementu {ThemeResource} zamiast {StaticResource}

Reguły, za pomocą których element ThemeResource jest rozpoznawany jako element w słowniku zasobów, są zazwyczaj takie same jak StaticResource. Odnośnik ThemeResource może rozszerzyć się na pliki ResourceDictionary , do których odwołuje się kolekcja ThemeDictionaries , ale może to zrobić również staticResource . Różnica polega na tym, że element ThemeResource może ponownie ocenić w czasie wykonywania, a element StaticResource nie może.

Zestaw kluczy w każdym słowniku motywów powinien zapewniać ten sam zestaw powiązanych zasobów, niezależnie od tego, który motyw jest aktywny. Jeśli dany zasób z kluczem istnieje w słowniku motywu HighContrast, to inny zasób o tej nazwie powinien również istnieć w słowniku motywu Jasny i Domyślny. Jeśli tak nie jest, wyszukiwanie zasobów może zakończyć się niepowodzeniem, gdy użytkownik przełączy motywy, a aplikacja nie będzie wyglądać prawidłowo. Istnieje jednak możliwość, że słownik motywu może zawierać zasoby powiązane z kluczem, do których odwołuje się wyłącznie wewnątrz tego samego zakresu w celu zapewnienia wartości podrzędnych; nie muszą one być takie same we wszystkich motywach.

Ogólnie rzecz biorąc, należy umieszczać zasoby w słownikach motywów i odwoływać się do tych zasobów przy użyciu elementu ThemeResource tylko wtedy, gdy te wartości mogą zmieniać się między motywami lub są obsługiwane przez wartości, które się zmieniają. Jest to odpowiednie dla tego rodzaju zasobów:

  • Pędzle, w szczególności kolory SolidColorBrush. Tworzą one około 80% użycia ThemeResource w domyślnych szablonach kontrolek XAML (generic.xaml).
  • Wartości pikseli dla obramowań, przesunięć, marginesu i wypełnienia itd.
  • Właściwości czcionki, takie jak FontFamily lub FontSize.
  • Kompletne szablony dla ograniczonej liczby kontrolek, które są zwykle stylizowane przez system i używane do dynamicznej prezentacji, takich jak GridViewItem i ListViewItem.
  • Style wyświetlania tekstu (zazwyczaj w celu zmiany koloru czcionki, tła i ewentualnego rozmiaru).

Środowisko uruchomieniowe systemu Windows udostępnia zestaw zasobów, które mają być przywoływalne przez themeResource. Są one wymienione jako część pliku XAML themeresources.xaml, który jest dostępny w folderze include/winrt/xaml/design w ramach zestawu Windows Software Development Kit (SDK). Aby uzyskać dokumentację dotyczącą pędzli motywów i dodatkowych stylów zdefiniowanych w pliku themeresources.xaml, zajrzyj do zasobów motywu XAML. Pędzle są udokumentowane w tabeli, która informuje, jaką wartość koloru ma każdy pędzel dla wszystkich trzech możliwych aktywnych motywów.

Definicje XAML stanów wizualizacji w szablonie kontrolki powinny używać odwołań ThemeResource za każdym razem, gdy istnieje zasób źródłowy, który może ulec zmianie z powodu zmiany motywu. Zmiana motywu systemowego zwykle nie powoduje również zmiany stanu wizualizacji. Zasoby muszą używać odwołań ThemeResource w tym przypadku, aby wartości mogły zostać przeliczone pod kątem nadal aktywnego stanu wizualnego. Jeśli na przykład masz stan wizualny, który zmienia kolor pędzla określonej części interfejsu użytkownika oraz jedną z jego właściwości, a kolor pędzla jest różny w zależności od motywu, powinieneś użyć odwołania ThemeResource, aby zapewnić wartość tej właściwości w szablonie domyślnym i wszelkie modyfikacje stanu wizualnego tego szablonu domyślnego.

Użycie elementu ThemeResource może być widoczne w serii wartości zależnych. Na przykład wartość Color używana przez element SolidColorBrush , który jest również zasobem kluczem, może używać odwołania ThemeResource . Jednak wszystkie właściwości interfejsu użytkownika korzystające z klucza zasobu SolidColorBrush będą również używać odwołania ThemeResource , dzięki czemu jest to konkretnie każda właściwość Typu pędzla, która umożliwia zmianę wartości dynamicznej po zmianie motywu.

Uwaga{ThemeResource} Ocena zasobów w czasie wykonywania podczas przełączania motywu jest obsługiwana w XAML dla Windows 8.1, ale nie jest obsługiwana w XAML w aplikacjach przeznaczanych na Windows 8.

Zasoby systemowe

Niektóre zasoby motywu odwołują się do wartości zasobów systemowych jako bazowej wartości podrzędnej. Zasób systemowy to specjalna wartość zasobu, która nie znajduje się w żadnym słowniku zasobów XAML. Te wartości opierają się na obsłudze XAML w środowisku uruchomieniowym Windows, aby przekazywać wartości z systemu i przedstawiać je w formie, do której zasób XAML może się odwołać. Na przykład istnieje zasób systemowy o nazwie "SystemColorButtonFaceColor", który reprezentuje kolor RGB. Ten kolor pochodzi z aspektów kolorów i motywów systemowych, które nie są specyficzne tylko dla środowiska uruchomieniowego Windows i aplikacji bazujących na nim.

Zasoby systemowe są często podstawowymi wartościami motywu o wysokim kontraście. Użytkownik kontroluje opcje kolorów dla motywu o wysokim kontraście, a użytkownik dokonuje tych wyborów przy użyciu funkcji systemowych, które również nie są specyficzne dla aplikacji Środowiska uruchomieniowego systemu Windows. Odwołując się do zasobów systemowych jako odwołań ThemeResource , domyślne zachowanie motywów o wysokim kontraście dla aplikacji Środowiska uruchomieniowego systemu Windows może używać tych wartości specyficznych dla motywu, które są kontrolowane przez użytkownika i udostępniane przez system. Ponadto odwołania są teraz oznaczone do ponownej oceny, jeśli system wykryje zmianę motywu w czasie działania.

Przykład użycia elementu {ThemeResource}

Oto kilka przykładowych plików XAML pobranych z domyślnego pliku generic.xaml i themeresources.xaml, aby zilustrować sposób używania elementu ThemeResource. Przyjrzymy się tylko jednemu szablonowi (domyślnemu przyciskowi) i zadeklarowaniu dwóch właściwości (tło i pierwszy plan), aby reagować na zmiany motywu.

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

W tym miejscu właściwości przyjmują wartość Brush, a odwołania do zasobów SolidColorBrush o nazwach ButtonBackgroundThemeBrush i ButtonForegroundThemeBrush są tworzone przy użyciu ThemeResource.

Te same właściwości są również dostosowywane przez niektóre stany wizualizacji dla przycisku. W szczególności kolor tła zmienia się po kliknięciu przycisku. W tym miejscu animacje Tło i Pierwszy plan w scenorysie stanu wizualizacji używają obiektów DiscreteObjectKeyFrame i odwołań do pędzli z elementem ThemeResource jako wartości ramki klucza.

<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>

Każda z tych pędzli jest zdefiniowana wcześniej w pliku generic.xaml: należy je zdefiniować przed użyciem szablonów, aby uniknąć odwołań w przód XAML. Oto te definicje dla słownika motywu "Default".

    <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" />
...

Następnie każdy z pozostałych słowników motywów ma również zdefiniowane te pędzle, na przykład:

        <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}" />

Tutaj wartość Color to kolejne odwołanie ThemeResource do zasobu systemowego. Jeśli odwołujesz się do zasobu systemowego i chcesz zmienić go w odpowiedzi na zmianę motywu, należy użyć elementu ThemeResource , aby utworzyć odwołanie.

Obsługa rozszerzenia znaczników {ThemeResource} dla narzędzi używanych w czasie projektowania

Program Microsoft Visual Studio może przedstawiać możliwe wartości kluczy w listach rozwijanych Microsoft IntelliSense przy użyciu rozszerzenia znaczników {ThemeResource} na stronie XAML. Na przykład po wpiseniu ciągu "{ThemeResource" zostaną wyświetlone wszystkie klucze zasobów z zasobów motywu XAML .

Gdy klucz zasobu istnieje w ramach dowolnego użycia {ThemeResource}, funkcja Przejdź do definicji (F12) może rozpoznać ten zasób i wyświetlić plik generic.xaml, w którym zdefiniowany jest zasób motywu na etapie projektowania. Ponieważ zasoby motywu są definiowane więcej niż raz (na motyw) Przejdź do definicji powoduje przejście do pierwszej definicji znalezionej w pliku, czyli definicji domyślnej. Jeśli chcesz uzyskać inne definicje, możesz wyszukać nazwę klucza w pliku i znaleźć definicje innych motywów.

  • Last updated on