Implementare il tema scuro

Prova il modo di comporre

Jetpack Compose è il toolkit per la UI consigliato per Android. Scopri come utilizzare i temi in Compose.

Combinazione di colori - Material Design 3 →

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

• Riduce notevolmente il consumo energetico, a seconda della tecnologia dello schermo del dispositivo.
• Migliora la visibilità per gli utenti ipovedenti e per quelli sensibili alla luce intensa.
• Semplifica 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 in Android 10 e versioni successive:

• Per attivare il tema scuro, utilizza l'impostazione di sistema andando su Impostazioni > Display > Tema.
• Utilizza il riquadro Impostazioni rapide per cambiare tema dalla barra delle notifiche, se attivato.
• Sui dispositivi Pixel, attiva la modalità Risparmio energetico per attivare contemporaneamente il tema scuro. Questo comportamento potrebbe non essere supportato da altri dispositivi.

Per istruzioni sull'applicazione di un tema scuro ai contenuti basati sul web utilizzando un componente WebView, consulta Oscurare i contenuti web in WebView.

Supportare il tema scuro nella tua app

Per supportare il tema scuro, imposta il tema della tua app, in genere disponibile in res/values/styles.xml, in modo che venga ereditato 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à notte controllata dal sistema e l'app ha un tema scuro predefinito quando è attivato.

Temi e stili

Evita di utilizzare colori o icone codificati in modo permanente destinati all'uso in un tema chiaro. Utilizza attributi del tema o risorse qualificate per la modalità buio.

Per il tema scuro, gli attributi del tema più importanti sono due:

• ?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, come gli attributi del tema ?attr/colorSurface e ?attr/colorOnSurface, fornisce un facile accesso a colori adatti. Puoi personalizzare questi attributi nel tema.

Cambiare i temi in-app

Puoi consentire agli utenti di modificare il tema dell'app mentre è in esecuzione. Le seguenti sono opzioni consigliate:

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

Queste opzioni corrispondono direttamente alle modalità di AppCompat.DayNight:

• Luce: MODE_NIGHT_NO.

• Scuro: MODE_NIGHT_YES.

• Predefinito di sistema: MODE_NIGHT_FOLLOW_SYSTEM.

Per cambiare tema:

• A partire dal livello API 31, utilizza UiModeManager#setApplicationNightMode per comunicare al sistema il tema in cui viene eseguita l'app. In questo modo il sistema può abbinare il tema durante la schermata iniziale.

• A livello API 30 e precedenti, utilizza AppCompatDelegate.setDefaultNightMode() per cambiare tema.

tema scuro forzato

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

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

Le app devono attivare la funzionalità Forza modalità buio impostando android:forceDarkAllowed="true" 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 Forza modalità Buio, testa a fondo la tua app ed escludi le visualizzazioni in base alle necessità.

Se la tua app utilizza un tema scuro, ad esempio Theme.Material, Force Dark non viene applicato. Allo stesso modo, se il tema della tua app eredita da un tema DayNight, Force Dark non viene applicato a causa del cambio automatico del tema.

Disattivare la modalità Buio forzato in una vista

La modalità Buio forzato può essere controllata su visualizzazioni specifiche con l'attributo di layout android:forceDarkAllowed o con setForceDarkAllowed().

Contenuti web

Per informazioni sull'utilizzo dei temi scuri nei contenuti basati sul web, consulta Oscurare 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 che utilizzi riflettano il tema dell'app host. Due esempi sono le notifiche e i widget di Avvio app.

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 delle notifiche personalizzate

Per i widget del launcher o se la tua app utilizza visualizzazioni personalizzate dei contenuti delle notifiche, prova i contenuti sia con il tema chiaro che con quello scuro.

Ecco alcuni errori comuni da evitare:

• Supponendo che il colore dello sfondo sia sempre chiaro.
• Codifica dei colori del testo.
• Impostazione di un colore di sfondo hardcoded durante l'utilizzo del colore del testo predefinito.
• Utilizzo di un'icona disegnabile di un colore statico.

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

Schermate di avvio

Se la tua app ha una schermata di avvio personalizzata, potresti doverla modificare in modo che 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 modifica della configurazione uiMode. Ciò significa che le attività vengono ricreate automaticamente.

In alcuni casi, potresti voler che sia un'app a gestire la modifica della configurazione. Ad esempio, potresti voler ritardare una modifica alla 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 metodo onConfigurationChanged() viene chiamato quando viene modificato il tema.

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

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

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