Implementare il tema scuro

Prova Compose
Jetpack Compose è il toolkit UI consigliato per Android. Scopri come utilizzare i temi in Compose.
Combinazione di colori - Material Design 3 →

Figura 1. Tema scuro.

Il tema scuro è disponibile su Android 10 (livello API 29) e versioni successive. Presenta i seguenti vantaggi:

  • Riduce notevolmente il consumo di energia, a seconda della tecnologia dello schermo del dispositivo.
  • Migliora la visibilità per gli utenti ipovedenti e per quelli sensibili alla luce intensa.
  • Facilita l'utilizzo di un dispositivo in un ambiente con scarsa illuminazione.

Il tema scuro viene applicato all'interfaccia utente del sistema Android e alle app in esecuzione sul dispositivo.

Esistono tre modi per attivare il tema scuro su Android 10 e versioni successive:

  • Utilizza l'impostazione di sistema andando su Impostazioni > Display > Tema per attivare il tema scuro.
  • Utilizza il riquadro Impostazioni rapide per cambiare tema dal riquadro delle notifiche, se attivato.
  • Sui dispositivi Pixel, attiva la modalità Risparmio energetico per attivare contemporaneamente il tema scuro. Altri dispositivi potrebbero non supportare questo comportamento.

Per istruzioni su come applicare un tema scuro ai contenuti web utilizzando un componente WebView, consulta Scurire i contenuti web in WebView.

Supportare il tema scuro nell'app

Per supportare il tema scuro, imposta il tema dell'app, in genere disponibile in res/values/styles.xml in modo che erediti da un tema DayNight:

<style name="AppTheme" parent="Theme.AppCompat.DayNight">

Puoi anche utilizzare il tema scuro dei componenti Material :

<style name="AppTheme" parent="Theme.MaterialComponents.DayNight">

In questo modo, il tema principale dell'app viene associato ai flag della modalità notturna controllati dal sistema e all'app viene assegnato un tema scuro predefinito quando è attivato.

Temi e stili

Evita di utilizzare colori o icone codificati che devono essere utilizzati con un tema chiaro. Utilizza invece gli attributi del tema o le risorse qualificate per la modalità notturna.

Due attributi del tema sono i più importanti per il tema scuro:

  • ?android:attr/textColorPrimary: un colore del testo generico. È quasi nero nel tema chiaro e quasi bianco nei temi scuri. Contiene uno stato disattivato.
  • ?attr/colorControlNormal: un colore dell'icona generico. Contiene uno stato disattivato.

Ti consigliamo di utilizzare i componenti Material Design, poiché il relativo sistema di temi di colore, ad esempio gli attributi del tema ?attr/colorSurface e ?attr/colorOnSurface, fornisce un facile accesso ai colori adatti. Puoi personalizzare questi attributi nel tuo tema.

Cambiare i temi in-app

Puoi consentire agli utenti di modificare il tema dell'app mentre è in esecuzione. Di seguito sono riportate le opzioni consigliate:

  • Chiaro
  • Scuro
  • Predefinito di sistema (l'opzione predefinita consigliata)

Queste opzioni vengono mappate direttamente alle modalità AppCompat.DayNight:

Per cambiare il tema:

tema scuro forzato

Android 10 offre tema scuro forzato, una funzionalità che consente agli sviluppatori di implementare rapidamente un tema scuro senza impostare esplicitamente un tema DayNight.

Il tema scuro forzato analizza ogni visualizzazione dell'app con tema chiaro e applica automaticamente un tema scuro prima che venga disegnato sullo schermo. Puoi utilizzare una combinazione di tema scuro forzato e implementazione nativa per ridurre il tempo necessario per implementare il tema scuro tema.

Le app devono attivare il tema scuro forzato impostando android:forceDarkAllowed="true" in nel tema dell'attività. Questo attributo è impostato su tutti i temi chiari forniti dal sistema e da AndroidX, ad esempio Theme.Material.Light. Quando utilizzi il tema scuro forzato, testa attentamente l'app ed escludi le visualizzazioni, se necessario.

Se l'app utilizza un tema scuro, ad esempio Theme.Material), il tema scuro forzato non viene applicato. Allo stesso modo, se il tema dell'app eredita da un tema DayNight, il tema scuro forzato non viene applicato a causa del cambio automatico del tema.

Disattivare il tema scuro forzato in una visualizzazione

Il tema scuro forzato può essere controllato su visualizzazioni specifiche con l' android:forceDarkAllowed attributo di layout o con setForceDarkAllowed().

Contenuti web

Per informazioni sull'utilizzo dei temi scuri nei contenuti web, consulta Scurire i contenuti web in WebView. Per un esempio di tema scuro applicato a una WebView, consulta la demo di WebView su GitHub .

Best practice

Le sezioni seguenti forniscono le best practice per l'implementazione dei temi scuri.

Notifiche e widget

Per le superfici UI che visualizzi sul dispositivo ma che non controlli direttamente, assicurati che tutte le visualizzazioni utilizzate riflettano il tema dell'app host. Due esempi sono le notifiche e i widget di avvio.

Notifiche

Utilizza i modelli di notifica forniti dal sistema, ad esempio MessagingStyle. Ciò significa che il sistema è responsabile dell'applicazione dello stile di visualizzazione corretto.

Widget e visualizzazioni di notifiche personalizzate

Per i widget di avvio o se l'app utilizza visualizzazioni di contenuti di notifiche personalizzate, testa i contenuti sia con il tema chiaro sia con quello scuro.

Di seguito sono riportati alcuni errori comuni da tenere d'occhio:

  • Supporre che il colore di sfondo sia sempre chiaro.
  • Codificare i colori del testo.
  • Impostare un colore di sfondo codificato durante l'utilizzo del colore del testo predefinito.
  • Utilizzare un'icona disegnabile con un colore statico.

In tutti questi casi, utilizza gli attributi del tema appropriati anziché i colori codificati.

Schermate di avvio

Se l'app ha una schermata di avvio personalizzata, potrebbe essere necessario modificarla in modo che lo rifletta il tema selezionato.

Rimuovi tutti i colori codificati, ad esempio i colori di sfondo impostati a livello di programmazione su bianco. Utilizza invece l'attributo del tema ?android:attr/colorBackground.

Modifiche alla configurazione

Quando il tema dell'app cambia, tramite l'impostazione di sistema o AppCompat, viene attivata una uiModemodifica della configurazione. Ciò significa che le attività vengono ricreate automaticamente.

In alcuni casi, potresti voler che un'app gestisca la modifica della configurazione. Ad esempio, potresti voler ritardare una modifica della configurazione perché è in riproduzione un video.

Un'app può gestire l'implementazione del tema scuro dichiarando che ogni Activity può gestire la modifica della configurazione uiMode:

<activity
    android:name=".MyActivity"
    android:configChanges="uiMode" />

Quando un Activity dichiara di gestire le modifiche alla configurazione, il relativo onConfigurationChanged() metodo viene chiamato quando si verifica una modifica del tema.

Per controllare il tema attuale, le app possono eseguire codice come il seguente:

Kotlin

val currentNightMode = configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
when (currentNightMode) {
    Configuration.UI_MODE_NIGHT_NO -> {} // Night mode is not active, we're using the light theme.
    Configuration.UI_MODE_NIGHT_YES -> {} // Night mode is active, we're using dark theme.
}

Java

int currentNightMode = configuration.uiMode & Configuration.UI_MODE_NIGHT_MASK;
switch (currentNightMode) {
    case Configuration.UI_MODE_NIGHT_NO:
        // Night mode is not active, we're using the light theme
        break;
    case Configuration.UI_MODE_NIGHT_YES:
        // Night mode is active, we're using dark theme
        break;
}