Gaya XAML

Artikel
07/13/2023

Anda dapat menyesuaikan tampilan aplikasi anda dalam banyak cara dengan menggunakan kerangka kerja XAML. Gaya memungkinkan Anda mengatur properti kontrol dan menggunakan kembali pengaturan tersebut untuk tampilan yang konsisten di beberapa kontrol.

WinUI dan gaya

Dimulai dengan WinUI 2.2, kami telah menggunakan Windows UI Library (WinUI) untuk memberikan pembaruan gaya visual baru di seluruh komponen UI kami. Jika Anda melihat UI Anda tidak memperbarui ke gaya terbaru, pastikan untuk memperbarui ke paket WinUI NuGet terbaru.

Dimulai dengan WinUI 2.6, kami menyediakan gaya baru untuk sebagian besar kontrol, dan sistem penerapan versi baru yang memungkinkan Anda kembali ke gaya kontrol sebelumnya jika diperlukan. Kami mendorong Anda untuk menggunakan gaya baru, karena lebih cocok dengan arah desain Windows. Namun, jika skenario Anda tidak dapat mendukung gaya baru, versi sebelumnya masih tersedia.

Anda dapat mengubah versi gaya dengan mengatur ControlsResourcesVersion properti pada XamlControlsResources yang Anda sertakan di saat Application.Resources Anda menggunakan WinUI versi 2. ControlsResourcesVersion default ke nilai Version2enum .

Mengatur nilai ini ke Version1 menyebabkan XamlControlsResources memuat versi gaya sebelumnya alih-alih gaya baru yang digunakan oleh versi WinUI terbaru. Mengubah properti ini saat runtime tidak didukung dan fungsionalitas isi ulang panas VisualStudio tidak akan berfungsi; namun, setelah Anda membangun kembali aplikasi Anda, Anda akan melihat gaya kontrol berubah.

<Application.Resources>
    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" 
                           ControlsResourcesVersion="Version1"/>
</Application.Resources>

Dasar-dasar gaya

Gunakan gaya untuk mengekstrak pengaturan properti visual ke sumber daya yang dapat digunakan kembali. Berikut adalah contoh yang memperlihatkan 3 tombol dengan gaya yang mengatur properti BorderBrush, BorderThickness , dan Foreground . Dengan menerapkan gaya, Anda dapat membuat kontrol tampak sama tanpa harus mengatur properti ini pada setiap kontrol secara terpisah.

Cuplikan layar tiga tombol bergaya yang disusun berdampingan.

Anda dapat menentukan gaya sebaris di XAML untuk kontrol, atau sebagai sumber daya yang dapat digunakan kembali. Tentukan sumber daya dalam file XAML halaman individual, dalam file App.xaml, atau dalam file XAML kamus sumber daya terpisah. File XAML kamus sumber daya dapat dibagikan di seluruh aplikasi, dan lebih dari satu kamus sumber daya dapat digabungkan dalam satu aplikasi. Di mana sumber daya ditentukan menentukan cakupan tempat sumber daya dapat digunakan. Sumber daya tingkat halaman hanya tersedia di halaman tempat sumber daya ditentukan. Jika sumber daya dengan kunci yang sama ditentukan di App.xaml dan di halaman, sumber daya di halaman akan mengambil alih sumber daya di App.xaml. Jika sumber daya ditentukan dalam file kamus sumber daya terpisah, cakupannya ditentukan oleh tempat kamus sumber daya direferensikan.

Dalam definisi Gaya , Anda memerlukan atribut TargetType dan koleksi satu atau beberapa elemen Setter . Atribut TargetType adalah string yang menentukan jenis FrameworkElement untuk menerapkan gaya. Nilai TargetType harus menentukan jenis turunan FrameworkElement yang ditentukan oleh Windows Runtime atau jenis kustom yang tersedia dalam rakitan yang dirujuk. Jika Anda mencoba menerapkan gaya ke kontrol dan jenis kontrol tidak cocok dengan atribut TargetType gaya yang coba Anda terapkan, pengecualian terjadi.

Setiap elemen Setter memerlukan Properti dan Nilai. Pengaturan properti ini menunjukkan properti kontrol apa yang diterapkan pengaturan, dan nilai yang akan diatur untuk properti tersebut. Anda dapat mengatur Setter.Value dengan sintaks atribut atau elemen properti. XAML di sini menunjukkan gaya yang diterapkan ke tombol yang ditampilkan sebelumnya. Dalam XAML ini, dua elemen Setter pertama menggunakan sintaks atribut, tetapi Setter terakhir, untuk properti BorderBrush , menggunakan sintaks elemen properti. Contoh tidak menggunakan atribut x:Key , sehingga gaya diterapkan secara implisit ke tombol. Menerapkan gaya secara implisit atau eksplisit dijelaskan di bagian berikutnya.

<Page.Resources>
    <Style TargetType="Button">
        <Setter Property="BorderThickness" Value="5" />
        <Setter Property="Foreground" Value="Black" />
        <Setter Property="BorderBrush" >
            <Setter.Value>
                <LinearGradientBrush StartPoint="0.5,0" EndPoint="0.5,1">
                    <GradientStop Color="Yellow" Offset="0.0" />
                    <GradientStop Color="Red" Offset="0.25" />
                    <GradientStop Color="Blue" Offset="0.75" />
                    <GradientStop Color="LimeGreen" Offset="1.0" />
                </LinearGradientBrush>
            </Setter.Value>
        </Setter>
    </Style>
</Page.Resources>

<StackPanel Orientation="Horizontal">
    <Button Content="Button"/>
    <Button Content="Button"/>
    <Button Content="Button"/>
</StackPanel>

Menerapkan gaya implisit atau eksplisit

Jika Anda menentukan gaya sebagai sumber daya, ada dua cara untuk menerapkannya ke kontrol Anda:

Secara implisit, dengan hanya menentukan TargetType untuk Gaya.
Secara eksplisit, dengan menentukan TargetType dan atribut x:Key untuk Gaya lalu dengan mengatur properti Gaya kontrol target dengan referensi ekstensi markup {StaticResource} yang menggunakan kunci eksplisit.

Jika gaya berisi atribut x:Key, Anda hanya dapat menerapkannya ke kontrol dengan mengatur properti Gaya kontrol ke gaya kunci. Sebaliknya, gaya tanpa atribut x:Key secara otomatis diterapkan ke setiap kontrol jenis targetnya, yang tidak memiliki pengaturan gaya eksplisit.

Berikut adalah dua tombol yang menunjukkan gaya implisit dan eksplisit.

tombol yang ditata secara implisit dan eksplisit.

Dalam contoh ini, gaya pertama memiliki atribut x:Key dan jenis targetnya adalah Tombol. Properti Gaya tombol pertama diatur ke kunci ini, sehingga gaya ini diterapkan secara eksplisit. Gaya kedua diterapkan secara implisit ke tombol kedua karena jenis targetnya adalah Tombol dan gaya tidak memiliki atribut x:Key.

<Page.Resources>
    <Style x:Key="PurpleStyle" TargetType="Button">
        <Setter Property="FontFamily" Value="Segoe UI"/>
        <Setter Property="FontSize" Value="14"/>
        <Setter Property="Foreground" Value="Purple"/>
    </Style>

    <Style TargetType="Button">
        <Setter Property="FontFamily" Value="Segoe UI"/>
        <Setter Property="FontSize" Value="14"/>
        <Setter Property="RenderTransform">
            <Setter.Value>
                <RotateTransform Angle="25"/>
            </Setter.Value>
        </Setter>
        <Setter Property="BorderBrush" Value="Green"/>
        <Setter Property="BorderThickness" Value="2"/>
        <Setter Property="Foreground" Value="Green"/>
    </Style>
</Page.Resources>

<Grid x:Name="LayoutRoot">
    <Button Content="Button" Style="{StaticResource PurpleStyle}"/>
    <Button Content="Button"/>
</Grid>

Menggunakan gaya berbasis

Untuk membuat gaya lebih mudah dipertahankan dan mengoptimalkan penggunaan kembali gaya, Anda dapat membuat gaya yang mewarisi dari gaya lain. Anda menggunakan properti BasedOn untuk membuat gaya yang diwariskan. Gaya yang mewarisi dari gaya lain harus menargetkan tipe kontrol yang sama atau kontrol yang berasal dari jenis yang ditargetkan oleh gaya dasar. Misalnya, jika gaya dasar menargetkan ContentControl, gaya yang didasarkan pada gaya ini dapat menargetkan ContentControl atau jenis yang berasal dari ContentControl seperti Button dan ScrollViewer. Jika nilai tidak diatur dalam gaya berdasarkan, nilai tersebut diwarisi dari gaya dasar. Untuk mengubah nilai dari gaya dasar, gaya berbasis akan menggantikan nilai tersebut. Contoh berikutnya memperlihatkan Tombol dan Kotak Centang dengan gaya yang mewarisi dari gaya dasar yang sama.

tombol gaya usign berdasarkan gaya.

Gaya dasar menargetkan ContentControl, dan mengatur properti Tinggi, dan Lebar . Gaya berdasarkan target gaya ini Kotak Centang dan Tombol, yang berasal dari ContentControl. Gaya berbasis mengatur warna yang berbeda untuk properti BorderBrush dan Foreground . (Anda biasanya tidak meletakkan batas di sekitar Kotak Centang. Kami melakukannya di sini untuk menunjukkan efek gaya.)

<Page.Resources>
    <Style x:Key="BasicStyle" TargetType="ContentControl">
        <Setter Property="Width" Value="130" />
        <Setter Property="Height" Value="30" />
    </Style>

    <Style x:Key="ButtonStyle" TargetType="Button"
           BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Orange" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Red" />
    </Style>

    <Style x:Key="CheckBoxStyle" TargetType="CheckBox"
           BasedOn="{StaticResource BasicStyle}">
        <Setter Property="BorderBrush" Value="Blue" />
        <Setter Property="BorderThickness" Value="2" />
        <Setter Property="Foreground" Value="Green" />
    </Style>
</Page.Resources>

<StackPanel>
    <Button Content="Button" Style="{StaticResource ButtonStyle}" Margin="0,10"/>
    <CheckBox Content="CheckBox" Style="{StaticResource CheckBoxStyle}"/>
</StackPanel>

Menggunakan alat untuk bekerja dengan gaya dengan mudah

Cara cepat untuk menerapkan gaya ke kontrol Anda adalah dengan mengklik kanan kontrol pada permukaan desain XAML Microsoft Visual Studio dan memilih Edit Gaya atau Edit Templat (tergantung pada kontrol yang Anda klik kanan). Anda kemudian dapat menerapkan gaya yang sudah ada dengan memilih Terapkan Sumber Daya atau tentukan gaya baru dengan memilih Buat Kosong. Jika Anda membuat gaya kosong, Anda diberi opsi untuk menentukannya di halaman, di file App.xaml, atau dalam kamus sumber daya terpisah.

Gaya ringan

Mengesampingkan kuas sistem umumnya dilakukan di tingkat Aplikasi atau Halaman, dan dalam kedua kasus, penimpaan warna akan memengaruhi semua kontrol yang mereferensikan kuas - dan di XAML banyak kontrol dapat mereferensikan sikat sistem yang sama.

<Page.Resources>
    <ResourceDictionary>
        <ResourceDictionary.ThemeDictionaries>
            <ResourceDictionary x:Key="Light">
                 <SolidColorBrush x:Key="ButtonBackground" Color="Transparent"/>
                 <SolidColorBrush x:Key="ButtonForeground" Color="MediumSlateBlue"/>
                 <SolidColorBrush x:Key="ButtonBorderBrush" Color="MediumSlateBlue"/>
            </ResourceDictionary>
        </ResourceDictionary.ThemeDictionaries>
    </ResourceDictionary>
</Page.Resources>

Untuk status seperti PointerOver (mouse diarahkan ke tombol), PointerPressed (tombol telah dipanggil), atau Dinonaktifkan (tombol tidak dapat berinteraksi). Akhiran ini ditambahkan ke nama gaya Ringan asli: ButtonBackgroundPointerOver, ButtonForegroundPressed, ButtonBorderBrushDisabled, dll. Memodifikasi kuas tersebut juga, akan memastikan bahwa kontrol Anda diwarnai secara konsisten dengan tema aplikasi Anda.

Menempatkan penimpaan kuas ini di tingkat App.Resources , akan mengubah semua tombol dalam seluruh aplikasi, bukan pada satu halaman.

Gaya per kontrol

Dalam kasus lain, mengubah satu kontrol pada satu halaman hanya untuk melihat cara tertentu, tanpa mengubah versi lain dari kontrol tersebut, diinginkan:

Cuplikan layar tiga tombol bergaya yang disusun satu di atas tombol lainnya.

<CheckBox Content="Normal CheckBox" Margin="5"/>
<CheckBox Content="Special CheckBox" Margin="5">
    <CheckBox.Resources>
        <ResourceDictionary>
            <ResourceDictionary.ThemeDictionaries>
                <ResourceDictionary x:Key="Light">
                    <SolidColorBrush x:Key="CheckBoxForegroundUnchecked"
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxForegroundChecked"
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxCheckGlyphForegroundChecked"
                        Color="White"/>
                    <SolidColorBrush x:Key="CheckBoxCheckBackgroundStrokeChecked"  
                        Color="Purple"/>
                    <SolidColorBrush x:Key="CheckBoxCheckBackgroundFillChecked"
                        Color="Purple"/>
                </ResourceDictionary>
            </ResourceDictionary.ThemeDictionaries>
        </ResourceDictionary>
    </CheckBox.Resources>
</CheckBox>
<CheckBox Content="Normal CheckBox" Margin="5"/>

Ini hanya akan mempengaruhi bahwa satu "Kotak Centang Khusus" pada halaman tempat kontrol itu ada.

Kontrol kustom

Saat Anda membangun kontrol kustom Anda sendiri yang mungkin secara visual dan/atau selaras secara fungsional dengan kontrol bawaan kami, pertimbangkan untuk menggunakan sumber daya gaya implisit dan Gaya ringan untuk menentukan konten kustom Anda. Anda dapat menggunakan sumber daya secara langsung, atau membuat alias baru untuk sumber daya.

Menggunakan sumber daya kontrol secara langsung

Misalnya, jika Anda menulis kontrol yang terlihat seperti Tombol, Anda dapat memiliki referensi kontrol sumber daya tombol secara langsung, seperti ini:

<Style TargetType="local:MyCustomControl">
  <Setter Property="Background" Value="{ThemeResource ButtonBackground}" />
  <Setter Property="BorderBrush" Value="{ThemeResource ButtonBorderBrush}" />
</Style>

Alias mengontrol sumber daya ke nama baru

Atau, jika Anda lebih suka membuat sumber daya Anda sendiri, Anda harus alias nama kustom tersebut ke sumber daya gaya Ringan default kami.

Misalnya, gaya kontrol kustom Anda mungkin memiliki definisi sumber daya khusus:

<Style TargetType="local:MyCustomControl">
  <Setter Property="Background" Value="{ThemeResource MyCustomControlBackground}" />
  <Setter Property="BorderBrush" Value="{ThemeResource MyCustomControlBorderBrush}"/>
</Style>

Dalam Kamus Sumber Daya atau definisi utama, Anda akan menghubungkan sumber daya gaya Ringan ke sumber daya kustom Anda:

<ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Default">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>        
    <ResourceDictionary x:Key="Light">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
        <StaticResource x:Key="MyCustomControlBackground" ResourceKey="ButtonBackground" />
        <StaticResource x:Key="MyCustomControlBorderBrush" ResourceKey="ButtonBorderBrush" />
    </ResourceDictionary>
</ResourceDictionary.ThemeDictionaries>

Diperlukan agar Anda menggunakan ThemeDictionary yang diduplikasi tiga kali untuk menangani tiga perubahan tema yang berbeda dengan benar (Default, Light, HighContrast).

Perhatian

Jika Anda menetapkan sumber daya gaya Ringan ke alias baru, dan juga mendefinisikan ulang sumber daya gaya Ringan, penyesuaian Anda mungkin tidak diterapkan jika pencarian sumber daya tidak dalam urutan yang benar. Misalnya, jika Anda mengambil ButtonBackground alih di tempat yang dicari sebelum MyCustomControlBackground ditemukan, penimpaan akan terlewatkan.

Hindari kontrol restyling

Pustaka Windows UI 2.2 atau yang lebih baru menyertakan gaya dan templat baru untuk WinUI dan kontrol sistem.

Cara terbaik untuk tetap terkini dengan gaya visual terbaru kami adalah dengan menggunakan paket WinUI 2 terbaru dan menghindari gaya dan templat kustom (juga dikenal sebagai templat ulang). Gaya masih merupakan cara mudah untuk menerapkan serangkaian nilai secara konsisten di seluruh kontrol di aplikasi Anda. Saat melakukan ini, pastikan untuk didasarkan pada gaya terbaru kami.

Untuk kontrol sistem yang menggunakan gaya WinUI (Windows.UI.Xaml.Controls namespace), atur BasedOn="{StaticResource Default<ControlName>Style}", di mana <ControlName> adalah nama kontrol. Contohnya:

<Style TargetType="TextBox" BasedOn="{StaticResource DefaultTextBoxStyle}">
    <Setter Property="Foreground" Value="Blue"/>
</Style>

Untuk kontrol WinUI 2 (Microsoft.UI.Xaml.Controls namespace), gaya default ditentukan dalam metadata, jadi hilangkan BasedOn.

Kontrol turunan

Jika Anda mendapatkan kontrol kustom dari kontrol XAML yang ada, itu tidak akan mendapatkan gaya WinUI 2 secara default. Untuk menerapkan gaya WinUI 2:

Buat Gaya baru dengan TargetType yang diatur ke kontrol kustom Anda.
Dasarkan Gaya pada gaya default kontrol tempat Anda berasal.

Salah satu skenario umum untuk ini adalah memperoleh kontrol baru dari ContentDialog. Contoh ini memperlihatkan cara membuat Gaya baru yang berlaku DefaultContentDialogStyle untuk dialog kustom Anda.

<ContentDialog
    x:Class="ExampleApp.SignInContentDialog"
    ... >

    <ContentDialog.Resources>
        <Style TargetType="local:SignInContentDialog" BasedOn="{StaticResource DefaultContentDialogStyle}"/>
        ...
    </ContentDialog.Resources> 
    <!-- CONTENT -->
</ContentDialog>

Properti templat

Setter gaya dapat digunakan untuk properti Templat Kontrol, dan pada kenyataannya ini membentuk sebagian besar gaya XAML umum dan sumber daya XAML aplikasi. Ini dibahas secara lebih rinci dalam topik Templat kontrol.