Aracılığıyla paylaş

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 Runtime, ç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 Runtime 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:

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 nasıl uygulanır 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 renk kümesi kaynağı sağlar. WinUI 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 Galerisi uygulaması, çoğu WinUI denetimi, özelliği ve işlevine ilişkin etkileşimli örnekler içerir. Uygulamayı Microsoft Store'dan edinin veya kaynak kodunu GitHub'dan alın.

Windows sistem kontrast 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 Runtime 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ık tema renklerine ek olarak, sistem vurgu rengi SystemAccentColor anahtarı kullanı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
Karanlık 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:

metin bloğu stilleri

Stil Weight Boyut
Açıklama yazısı Düzenli 12
Body Düzenli 14
Gövde Güçlü Semibold 14
Büyük Gövde Düzenli 18
Gövde Büyük Güçlü Semibold 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 üzerinde WinUI:

Tip

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

Temel Zengin Metin Blok Stili

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

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

Ek anahtarlı bir Stil tanımları kümesini, bir Düğme'yi varsayılan örtük stilinden farklı bir şekilde stillendirmek için uygulayabilirsiniz.

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.

** İşte üzerine NavigationBackButtonNormalStyle kaynağı uygulanan bir Düğme.

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

Şunun gibi görünür:

Geri düğmesi olarak stillenmiş bir düğme

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 rengini değiştirmek istiyorsunuz, fakat yüksek karşıtlıkta değilken, 'nin temanız için doğru renge işaret ettiğinden emin olmak için myBrush'dan yararlanı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, yazılım çatısı denetiminizin görsel ağacı üzerinde ilerlerken tema değişimlerini işlerken 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 öğeleri algoritma yürüterek ve üzerlerinde veya özelliklerine ayarlanmış nesnelerde ayarlanmış tüm {ThemeResource} işaretleme uzantısı ifadelerini güncelleştirir. Sorun burada oluşur; çerçeve fırça kaynağını tarar ve {ThemeResource} işaretleme uzantısını kullanarak rengini belirttiği için yeniden değerlendirilir.

Bu noktada yapı, tema sözlüğünüzü kirletmiş gibi görünüyor çünkü artık bir sözlükten renk ayarına sahip olan kaynak, başka bir sözlükten geliyor.

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 kontrast tema ayarları için kullanması gereken belirli renkleri belirlemelerine 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.

  • Last updated on