XAML tema kaynakları

XAML'deki tema kaynakları, hangi sistem temasının etkin olduğuna bağlı olarak farklı değerler uygulayan bir kaynak kümesidir. XAML çerçevesinin desteklediği 3 tema vardır: "Açık", "Koyu" ve "HighContrast".

Önkoşullar: Bu konuda ResourceDictionary ve XAML kaynak başvurularını okuduğunuz varsayılır.

Tema kaynakları ve statik kaynaklar

Mevcut bir XAML kaynak sözlüğünden bir XAML kaynağına başvurabilen iki XAML işaretleme uzantısı vardır: {StaticResource} işaretleme uzantısı ve {ThemeResource} işaretleme uzantısı.

{ThemeResource} işaretleme uzantısının değerlendirilmesi, uygulama yüklendiğinde ve daha sonra tema çalışma zamanında her değiştiğinde gerçekleşir. Bu genellikle kullanıcının cihaz ayarlarını değiştirmesinin veya uygulama içindeki geçerli temasını değiştiren programlı bir değişikliğin sonucudur.

Buna karşılık, bir {StaticResource} işaretleme uzantısı yalnızca XAML uygulama tarafından ilk kez yüklendiğinde değerlendirilir. Güncelleştirilmez. XAML'nizdeki bulma ve değiştirme işleminin uygulama başlatma sırasında gerçek çalışma zamanı değeriyle değiştirilmesine benzer.

Kaynak sözlüğü yapısındaki tema kaynakları

Her tema kaynağı, themeresources.xaml XAML dosyasının bir parçasıdır. Tasarım amacıyla, themeresources.xaml bir Windows Yazılım Geliştirme Seti (SDK) yüklemesinden \(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic klasöründe kullanılabilir. themeresources.xaml dosyasındaki kaynak sözlükleri de aynı dizindeki generic.xaml dosyasında yeniden oluşturulur.

Windows Çalışma Zamanı, çalışma zamanı araması için bu fiziksel dosyaları kullanmaz. Bu nedenle, bunlar özel olarak bir DesignTime klasöründedir ve varsayılan olarak uygulamalara kopyalanmamıştır. Bunun yerine, bu kaynak sözlükleri Bellekte Windows Çalışma Zamanı'nın bir parçası olarak bulunur ve uygulamanızın tema kaynaklarına (veya sistem kaynaklarına) yönelik XAML kaynak başvuruları çalışma zamanında orada çözümleniyor.

Özel tema kaynakları için yönergeler

Kendi özel tema kaynaklarınızı tanımlayıp kullanırken şu yönergeleri izleyin:

• "HighContrast" sözlüğünüze ek olarak hem "Açık" hem de "Koyu" için tema sözlüklerini belirtin. Anahtar olarak "Varsayılan" ile bir ResourceDictionary oluşturabilmenize rağmen, açık olması ve bunun yerine "Açık", "Koyu" ve "HighContrast" kullanılması tercih edilir.

• Şunun içinde {ThemeResource} işaretleme uzantısını kullanın: Stiller, Ayarlayıcılar, Denetim şablonları, Özellik ayarlayıcıları ve Animasyonlar.

• Kaynak tanımlarınızda ThemeDictionaries içinde {ThemeResource} işaretleme uzantısını kullanmayın. Bunun yerine {StaticResource} işaretleme uzantısını kullanın.

  ÖZEL DURUM: ThemeDictionaries'ınızdaki uygulama temasından bağımsız kaynaklara başvurmak için {ThemeResource} işaretleme uzantısını kullanabilirsiniz. Bu kaynaklara örnek olarak, gibi SystemAccentColortema rengi kaynakları veya genellikle gibi SystemColorButtonFaceColor"SystemColor" ön ekli sistem rengi kaynakları verilebilir.

Dikkat

Bu yönergeleri izlemezseniz uygulamanızda temalarla ilgili beklenmeyen davranışlar görebilirsiniz. Daha fazla bilgi için Sorun giderme tema kaynakları bölümüne bakın.

XAML renk rampası ve temaya bağımlı fırçalar

"Açık", "Koyu" ve "HighContrast" temaları için birleştirilmiş renk kümesi, XAML'deki Windows renk rampasını oluşturur. sistem temalarını değiştirmek veya kendi XAML öğelerinize tema uygulamak istediğinizde, renk kaynaklarının nasıl yapılandırıldığını anlamanız önemlidir.

Windows uygulamanızda renk uygulama hakkında ek bilgi için bkz. Windows uygulamalarında renk.

Açık ve Koyu tema renkleri

XAML çerçevesi, "Açık" ve "Koyu" temalar için uyarlanmış değerlere sahip bir dizi color kaynağı sağlar. WinUI 2 için tema kaynakları Ortak tema kaynakları Xaml dosyasında tanımlanır. Renk adları amaçlanan kullanımlarını çok açıklayıcıdır ve her Color kaynağı için karşılık gelen bir SolidColorBrush kaynağı vardır.

Tip

Bu renklere görsel bir genel bakış için bkz. WinUI 3 Galeri uygulaması: Renkler

WinUI 3 Galeri uygulaması çoğu WinUI 3 denetimi, özelliği ve işlevselliğine ilişkin etkileşimli örnekler içerir. Uygulamayı Microsoft Store'dan alın veya GitHub'dan kaynak kodunu alın

Windows sistem karşıtlığı tema renkleri

XAML çerçevesi tarafından sağlanan kaynak kümesine ek olarak, Windows sistem paletinden türetilen bir renk değerleri kümesi vardır. Bu renkler Windows Çalışma Zamanı veya Windows uygulamalarına özgü değildir. Ancak, XAML Fırçası kaynaklarının çoğu sistem çalışırken (ve uygulama çalışırken) "HighContrast" temasını kullanarak bu renkleri kullanır. XAML çerçevesi bu sistem genelindeki renkleri anahtarlı kaynaklar olarak sağlar. Anahtarlar adlandırma biçimini izler: SystemColor[name]Color.

Karşıtlık temalarını destekleme hakkında daha fazla bilgi için bkz . Karşıtlık temaları.

Sistem vurgu rengi

Sistem karşıtlığı tema renklerine ek olarak, sistem vurgu rengi anahtarı SystemAccentColorkullanılarak özel bir renk kaynağı olarak sağlanır. Çalışma zamanında bu kaynak, kullanıcının Windows kişiselleştirme ayarlarında vurgu rengi olarak belirttiği rengi alır.

Uyarı

Sistem renk kaynaklarını geçersiz kılmak mümkün olsa da, özellikle karşıtlık teması ayarları için kullanıcının renk seçimlerine saygı duymayı tercih etmek en iyi yöntemdir.

Temaya bağımlı fırçalar

Önceki bölümlerde gösterilen renk kaynakları, sistem teması kaynak sözlüklerindeki SolidColorBrush kaynaklarının Color özelliğini ayarlamak için kullanılır. Rengi XAML öğelerine uygulamak için fırça kaynaklarını kullanırsınız.

Şimdi bu fırçanın renk değerinin çalışma zamanında nasıl belirlendiğini inceleyelim. "Açık" ve "Koyu" kaynak sözlüklerinde bu fırça şöyle tanımlanır:

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

"HighContrast" kaynak sözlüğünde bu fırça şöyle tanımlanır:

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

Bu fırça bir XAML öğesine uygulandığında, rengi bu tabloda gösterildiği gibi geçerli tema tarafından çalışma zamanında belirlenir.

Theme	Renk kaynağı	Çalışma zamanı değeri
Light	TextFillColorPrimary	#E4000000
Koyu	TextFillColorPrimary	#FFFFFFFF
HighContrast	SystemColorWindowTextColor	Metin ayarlarında belirtilen renk.

XAML türü rampası

themeresources.xaml dosyası, özellikle TextBlock veya RichTextBlock için kullanıcı arabiriminizdeki metin kapsayıcılarına uygulayabileceğiniz bir Stil tanımlayan çeşitli kaynakları tanımlar. Bunlar varsayılan örtük stiller değildir. Bunlar, Yazı tipleri için yönergeler bölümünde belgelenen Windows türü rampası ile eşleşen XAML kullanıcı arabirimi tanımları oluşturmanızı kolaylaştırmak için sağlanır.

Bu stiller, metin kapsayıcısının tamamına uygulanmasını istediğiniz metin özniteliklerine yöneliktir. Stillerin yalnızca metnin bölümlerine uygulanmasını istiyorsanız, kapsayıcı içindeki metin öğelerinde, örneğin TextBlock.Inlines içinde Çalıştır'da veya RichTextBlock.Blocks'takibir Paragrafta öznitelikleri ayarlayın.

TextBlock'a uygulandığında stiller şöyle görünür:

Stil	Weight	Boyut
Açıklama yazısı	Düzenli	12
Body	Düzenli	14
Gövde Güçlü	Semibold	14
Gövde Büyük	Düzenli	18
Altyazı	Semibold	20
Title	Semibold	28
Başlık Büyük	Semibold	40
Ekran	Semibold	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="Subtitle" Style="{StaticResource SubtitleTextBlockStyle}"/>
<TextBlock Text="Title" Style="{StaticResource TitleTextBlockStyle}"/>
<TextBlock Text="Title Large" Style="{StaticResource TitleLargeTextBlockStyle}"/>
<TextBlock Text="Display" Style="{StaticResource DisplayTextBlockStyle}"/>

Uygulamanızda Windows tür rampasını kullanma hakkında yönergeler için bkz. Windows uygulamalarında tipografi.

XAML stillerinin ayrıntıları için bkz. GitHub'da WinUI:

• Resim Yazısı TextBlockStyle
• Gövde MetniBlockStyle
• Gövde Güçlü TextBlockStyle

• Subtitle TextBlockStyle
• Başlık TextBlockStyle
• Başlık Büyük TextBlockStyle
• TextBlockStyle Görüntüle

Tip

Bu stiller hakkında görsel bir genel bakış için bkz. WinUI 3 Galeri uygulaması: Tipografi

BaseRichTextBlockStyle

TargetType: RichTextBlock

Diğer tüm RichTextBlock kapsayıcı stilleri için ortak özellikleri sağlar.

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

<!-- Style definition -->
<Style x:Key="BaseRichTextBlockStyle" TargetType="RichTextBlock">
    <Setter Property="FontFamily" Value="Segoe UI"/>
    <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>

Not: RichTextBlock stilleri, TextBlock'un sahip olduğu tüm metin rampa stillerine sahip değildir. Bunun nedeni, RichTextBlock için blok tabanlı belge nesne modelinin tek tek metin öğelerinde öznitelikleri ayarlamayı kolaylaştırmasıdır. Ayrıca, XAML içerik özelliğini kullanarak TextBlock.Text ayarlandığında, stil için metin öğesi olmadığı ve bu nedenle kapsayıcıyı stil olarak oluşturmanız gerekeceği bir durum ortaya çıkıyor. Metin içeriğinin her zaman Paragraf gibi belirli metin öğelerinde olması gerektiğinden, sayfa üst bilgisi, sayfa alt başlığı ve benzer metin rampası tanımları için XAML stillerini uygulayabileceğiniz RichTextBlock için bu bir sorun değildir.

Çeşitli Adlandırılmış stiller

Düğmeyi varsayılan örtük stilinden farklı bir stile uygulamak için ek anahtarlı Stil tanımları kümesi vardır.

NavigationBackButtonNormalStyle

TargetType: Düğme

Bu Stil , bir düğme için bir gezinti uygulamasının geri gezinti düğmesi olabilecek eksiksiz bir şablon sağlar. Varsayılan boyutlar 40 x 40 pikseldir. Stili uyarlamak için DüğmenizdekiHeight, Width, FontSize ve diğer özellikleri açıkça ayarlayabilir veya BasedOn kullanarak türetilmiş bir stil oluşturabilirsiniz.

NavigationBackButtonNormalStyle kaynağının uygulandığı düğme aşağıdadır.

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

Şunun gibi görünür:

NavigationBackButtonSmallStyle

TargetType: Düğme

Bu Stil , bir düğme için bir gezinti uygulamasının geri gezinti düğmesi olabilecek eksiksiz bir şablon sağlar. NavigationBackButtonNormalStyle'a benzer, ancak boyutları 30 x 30 pikseldir.

NavigationBackButtonSmallStyle kaynağının uygulandığı düğme aşağıdadır.

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

Tema kaynaklarıyla ilgili sorunları giderme

Tema kaynaklarını kullanma yönergelerini izlemezseniz uygulamanızda temalarla ilgili beklenmeyen davranışlar görebilirsiniz.

Örneğin, açık temalı bir açılır menü açtığınızda, koyu temalı uygulamanızın bölümleri de açık temadaymış gibi değişir. Ya da açık temalı bir sayfaya gidip geri dönerseniz, özgün koyu temalı sayfa (veya bölümlerini) artık açık temada gibi görünür.

Bu tür sorunlar genellikle yüksek karşıtlıklı senaryoları desteklemek için bir "Varsayılan" tema ve "HighContrast" teması sağladığınızda ve ardından uygulamanızın farklı bölümlerinde hem "Açık" hem de "Koyu" temaları kullandığınızda ortaya çıkar.

Örneğin, şu tema sözlüğü tanımını göz önünde bulundurun:

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

Sezgisel olarak, bu doğru görünüyor. Yüksek karşıtlıktayken işaret edilen myBrush rengi değiştirmek istiyorsunuz, ancak yüksek karşıtlıkta değilse temanız için doğru renge işaret ettiğinden emin olmak için myBrush kullanırsınız. Uygulamanızda hiçbir zaman görsel ağacı içindeki öğelerde FrameworkElement.RequestedTheme ayarlanmadıysa, bu genellikle beklendiği gibi çalışır. Ancak, görsel ağacınızın farklı bölümlerini yeniden temalandırmaya başladığınızda uygulamanızda sorunlarla karşılaşırsınız.

Sorun, fırçaların diğer XAML türlerinin çoğundan farklı olarak paylaşılan kaynaklar olması nedeniyle oluşur. XAML alt ağaçlarında aynı fırça kaynağına başvuran farklı temalara sahip 2 öğeniz varsa, çerçeve her alt ağaçta {ThemeResource} işaretleme uzantısı ifadelerini güncelleştirmek için adım adım ilerlediğinden, paylaşılan fırça kaynağındaki değişiklikler diğer alt ağaçta yansıtılır ve bu sizin istediğiniz sonuç değildir.

Bunu düzeltmek için ,"HighContrast"a ek olarak "Açık" ve "Koyu" temaları için "Varsayılan" sözlüğü ayrı tema sözlükleriyle değiştirin:

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

Ancak, bu kaynaklardan herhangi birine Ön Plan gibi devralınan özelliklerde başvurulduysa sorunlar yine de oluşur. Özel denetim şablonunuz {ThemeResource} işaretleme uzantısını kullanarak öğenin ön plan rengini belirtebilir, ancak çerçeve devralınan değeri alt öğelere yaydığında, {ThemeResource} işaretleme uzantısı ifadesi tarafından çözümlenen kaynağa doğrudan başvuru sağlar. Bu durum, çerçeve denetiminizin görsel ağacında ilerlerken tema değiştiğinde sorunlara neden olur. Yeni bir fırça kaynağı almak için {ThemeResource} işaretleme uzantısı ifadesini yeniden değerlendirir, ancak henüz bu başvuruyu denetiminizin alt öğelerine yaymaz; bu, sonraki ölçü geçişi gibi daha sonra gerçekleşir.

Sonuç olarak, tema değişikliğine yanıt olarak denetim görsel ağacını yürüdükten sonra, çerçeve alt öğelere kılavuzlar ve üzerinde veya özelliklerinde ayarlanan nesnelerde ayarlanan tüm {ThemeResource} işaretleme uzantısı ifadelerini güncelleştirir. Sorun burada oluşur; çerçeve fırça kaynağını gösterir ve {ThemeResource} işaretleme uzantısını kullanarak rengini belirttiğinden yeniden değerlendirilir.

Bu noktada çerçeve tema sözlüğünüzü kirletmiş gibi görünüyor çünkü artık başka bir sözlükten renk kümesine sahip bir sözlükten bir kaynağa sahip.

Bu sorunu çözmek için {ThemeResource} işaretleme uzantısı yerine {StaticResource} işaretleme uzantısını kullanın. Yönergeler uygulandığında, tema sözlükleri şöyle görünür:

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

{ThemeResource} işaretleme uzantısının {StaticResource} işaretleme uzantısı yerine "HighContrast" sözlüğünde hala kullanıldığına dikkat edin. Bu durum, yönergelerde daha önce belirtilen özel durum kapsamındadır. "HighContrast" teması için kullanılan fırça değerlerinin çoğu, sistem tarafından genel olarak denetlenen ancak özel olarak adlandırılmış bir kaynak olarak XAML'ye (adında 'SystemColor' ön ekleri bulunanlar) kullanıma sunulan renk seçeneklerini kullanır. Sistem, kullanıcının Erişim Kolaylığı Merkezi aracılığıyla karşıtlık teması ayarları için kullanılması gereken belirli renkleri ayarlamasına olanak tanır. Bu renk seçenekleri özel olarak adlandırılmış kaynaklara uygulanır. XAML çerçevesi, sistem düzeyinde değişiklik yaptıklarını algıladığında bu fırçaları güncelleştirmek için aynı tema değiştirme olayını kullanır. Bu nedenle {ThemeResource} işaretleme uzantısı burada kullanılır.