Merespons perubahan tema sistem

Telusuri contoh

Perangkat biasanya menyertakan tema terang dan gelap, yang masing-masing mengacu pada serangkaian preferensi penampilan yang luas yang dapat diatur pada tingkat sistem operasi. Aplikasi harus menghormati tema sistem ini, dan segera merespons ketika tema sistem berubah.

Tema sistem dapat berubah karena berbagai alasan, tergantung pada konfigurasi perangkat. Ini termasuk tema sistem yang diubah secara eksplisit oleh pengguna, terpengaruh oleh perubahan waktu sepanjang hari, dan dipengaruhi oleh faktor lingkungan seperti cahaya rendah.

Aplikasi .NET Multi-platform App UI (.NET MAUI) dapat merespons perubahan tema sistem dengan memanfaatkan sumber daya melalui AppThemeBinding ekstensi markup, serta dengan metode SetAppThemeColor dan SetAppTheme<T> ekstensi.

Nota

Aplikasi .NET MAUI dapat merespons perubahan tema sistem pada iOS 13 atau yang lebih tinggi, Android 10 (API 29) atau yang lebih tinggi, macOS 10.14 atau lebih tinggi, dan Windows 10 atau lebih tinggi.

Cuplikan layar berikut menunjukkan halaman bertema, untuk tema sistem cahaya di iOS dan tema sistem gelap di Android:

Menentukan dan menggunakan sumber daya tema

Sumber daya untuk tema terang dan gelap dapat dikonsumsi dengan ekstensi markup AppThemeBinding, serta metode ekstensi SetAppThemeColor dan SetAppTheme<T>. Dengan pendekatan ini, sumber daya secara otomatis diterapkan berdasarkan nilai tema sistem saat ini. Selain itu, objek yang menggunakan sumber daya ini secara otomatis diperbarui jika tema sistem berubah saat aplikasi berjalan.

Ekstensi markup AppThemeBinding

Ekstensi AppThemeBinding markup memungkinkan Anda menggunakan sumber daya, seperti gambar atau warna, berdasarkan tema sistem saat ini.

Ekstensi markup AppThemeBinding didukung oleh kelas AppThemeBindingExtension, yang menentukan properti berikut:

• Default, dari jenis object, yang Anda tetapkan sebagai sumber daya yang akan digunakan secara default.
• Light, dari jenis object, yang Anda atur ke sumber daya yang akan digunakan saat perangkat menggunakan tema cahayanya.
• Dark, dari jenis object, yang Anda atur ke sumber daya yang akan digunakan saat perangkat menggunakan tema gelapnya.
• Value, dari jenis object, yang mengembalikan sumber daya yang saat ini digunakan oleh ekstensi markup.

Nota

Parser XAML memungkinkan kelas AppThemeBindingExtension disingkat sebagai AppThemeBinding.

Properti Default adalah properti konten dari AppThemeBindingExtension. Oleh karena itu, untuk ekspresi markup XAML yang dinyatakan dengan kurung kurawal, Anda dapat menghilangkan bagian Default= dari ekspresi asalkan itu adalah argumen pertama.

Contoh XAML berikut menunjukkan cara menggunakan ekstensi markup AppThemeBinding:

<StackLayout>
    <Label Text="This text is green in light mode, and red in dark mode."
           TextColor="{AppThemeBinding Light=Green, Dark=Red}" />
    <Image Source="{AppThemeBinding Light=lightlogo.png, Dark=darklogo.png}" />
</StackLayout>

Dalam contoh ini, warna teks pertama Label diatur ke hijau ketika perangkat menggunakan tema terangnya, dan diatur ke merah saat perangkat menggunakan tema gelapnya. Demikian pula, Image menampilkan file gambar yang berbeda berdasarkan tema sistem saat ini.

Sumber daya yang ditentukan dalam ResourceDictionary dapat digunakan dalam sebuah AppThemeBinding dengan ekstensi markup StaticResource.

<ContentPage ...>
    <ContentPage.Resources>

        <!-- Light colors -->
        <Color x:Key="LightPrimaryColor">WhiteSmoke</Color>
        <Color x:Key="LightSecondaryColor">Black</Color>

        <!-- Dark colors -->
        <Color x:Key="DarkPrimaryColor">Teal</Color>
        <Color x:Key="DarkSecondaryColor">White</Color>

        <Style x:Key="ButtonStyle"
               TargetType="Button">
            <Setter Property="BackgroundColor"
                    Value="{AppThemeBinding Light={StaticResource LightPrimaryColor}, Dark={StaticResource DarkPrimaryColor}}" />
            <Setter Property="TextColor"
                    Value="{AppThemeBinding Light={StaticResource LightSecondaryColor}, Dark={StaticResource DarkSecondaryColor}}" />
        </Style>

    </ContentPage.Resources>

    <Grid BackgroundColor="{AppThemeBinding Light={StaticResource LightPrimaryColor}, Dark={StaticResource DarkPrimaryColor}}">
      <Button Text="MORE INFO"
              Style="{StaticResource ButtonStyle}" />
    </Grid>    
</ContentPage>    

Dalam contoh ini, warna latar belakang Grid dan gaya Button berubah berdasarkan apakah perangkat menggunakan tema terang atau tema gelapnya.

Selain itu, sumber daya yang ditentukan dalam ResourceDictionary juga dapat digunakan dalam AppThemeBinding dengan ekstensi markup DynamicResource.

<ContentPage ...>
    <ContentPage.Resources>
        <Color x:Key="Primary">DarkGray</Color>
        <Color x:Key="Secondary">HotPink</Color>
        <Color x:Key="Tertiary">Yellow</Color>
        <Style x:Key="labelStyle" TargetType="Label">
            <Setter Property="Padding" Value="5"/>
            <Setter Property="TextColor" Value="{AppThemeBinding Light={StaticResource Secondary}, Dark={StaticResource Primary}}" />
            <Setter Property="BackgroundColor" Value="{AppThemeBinding Light={DynamicResource Primary}, Dark={DynamicResource Secondary}}" />
        </Style>
    </ContentPage.Resources>
    <Label x:Name="myLabel"
           Style="{StaticResource labelStyle}"/>
</ContentPage>

Metode ekstensi

.NET MAUI mencakup metode ekstensi SetAppThemeColor dan SetAppTheme<T> yang memungkinkan objek VisualElement merespons perubahan tema sistem.

Metode SetAppThemeColor memungkinkan penentuan objek Color yang akan diatur pada properti target berdasarkan tema sistem saat ini:

Label label = new Label();
label.SetAppThemeColor(Label.TextColorProperty, Colors.Green, Colors.Red);

Dalam contoh ini, warna Label teks diatur ke hijau ketika perangkat menggunakan tema terangnya, dan diatur ke merah saat perangkat menggunakan tema gelapnya.

Metode SetAppTheme<T> ini memungkinkan penentuan objek dari jenis T yang akan diatur pada properti target berdasarkan tema sistem yang sedang digunakan.

Image image = new Image();
image.SetAppTheme<FileImageSource>(Image.SourceProperty, "lightlogo.png", "darklogo.png");

Dalam contoh ini, Image ditampilkan lightlogo.png ketika perangkat menggunakan tema terangnya, dan darklogo.png ketika perangkat menggunakan tema gelapnya.

Mendeteksi tema sistem saat ini

Tema sistem saat ini dapat dideteksi dengan mendapatkan nilai Application.RequestedTheme properti:

AppTheme currentTheme = Application.Current.RequestedTheme;

Properti RequestedTheme mengembalikan AppTheme anggota enumerasi. Enumerasi AppTheme menentukan anggota berikut:

• Unspecified, yang menunjukkan bahwa perangkat menggunakan tema yang tidak ditentukan.
• Light, yang menunjukkan bahwa perangkat menggunakan tema terang.
• Dark, yang menunjukkan bahwa perangkat menggunakan tema gelapnya.

Mengatur tema pengguna saat ini

Tema yang digunakan oleh aplikasi dapat diatur dengan Application.UserAppTheme properti , yang berjenis AppTheme, terlepas dari tema sistem mana yang saat ini beroperasi:

Application.Current.UserAppTheme = AppTheme.Dark;

Dalam contoh ini, aplikasi diatur untuk menggunakan tema yang ditentukan untuk mode gelap sistem, terlepas dari tema sistem mana yang saat ini beroperasi.

Nota

Atur properti UserAppTheme ke AppTheme.Unspecified untuk menetapkan tema sistem operasi secara default.

Bereaksi terhadap perubahan tema

Tema sistem pada perangkat dapat berubah karena berbagai alasan, tergantung pada bagaimana perangkat dikonfigurasi. Aplikasi MAUI .NET dapat diberi tahu ketika tema sistem berubah dengan menangani Application.RequestedThemeChanged event:

Application.Current.RequestedThemeChanged += (s, a) =>
{
    // Respond to the theme change
};

Objek AppThemeChangedEventArgs , yang menyertai RequestedThemeChanged peristiwa, memiliki satu properti bernama RequestedTheme, dari jenis AppTheme. Properti ini dapat diperiksa untuk mendeteksi tema sistem yang diminta.

Penting

Untuk menanggapi perubahan tema di Android, kelas Anda MainActivity harus menyertakan ConfigChanges.UiMode bendera di Activity atribut . Aplikasi .NET MAUI yang dibuat dengan templat proyek Visual Studio secara otomatis menyertakan bendera ini.