Implementare il tema scuro

Prova la funzionalità Scrivi

Jetpack Compose è il toolkit per l'interfaccia utente consigliato per Android. Scopri come utilizzare i temi in Scrivi.

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 di energia, a seconda della tecnologia dello schermo del dispositivo.
• Migliora la visibilità per gli utenti ipovedenti e per chi è sensibile alla luminosità 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, vai a Impostazioni > Display > Tema per usare l'impostazione di sistema.
• Utilizza il riquadro Impostazioni rapide per cambiare tema dalla barra delle notifiche, se abilitato.
• Sui Pixel, attiva la modalità Risparmio energetico per attivare contemporaneamente il tema scuro. Questo comportamento potrebbe non essere supportato da altri dispositivi.

Per istruzioni su come applicare un tema scuro ai contenuti web utilizzando un componente WebView, consulta Renderizzare più scuri i contenuti web in WebView.

Supportare il tema scuro nell'app

Per supportare il tema scuro, imposta il tema dell'app, che in genere si trova 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 di Material Components:

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

In questo modo, il tema principale dell'app viene collegato agli indicatori della modalità notturna controllati dal sistema e, se questa è attivata, all'app viene assegnato un tema scuro predefinito.

Temi e stili

Evita di utilizzare colori o icone hardcoded destinati all'utilizzo con un tema chiaro. Utilizza invece gli attributi tema o le risorse con qualifica notturna.

Per il tema scuro sono fondamentali due attributi:

• ?android:attr/textColorPrimary: un colore di testo generico. È quasi nero nel tema chiaro e quasi bianco nei temi scuri. Contiene uno stato disabilitato.
• ?attr/colorControlNormal: un colore di icone generico. Contiene uno stato disabilitato.

Ti consigliamo di utilizzare i componenti di Material Design, poiché il relativo sistema di temi a colori, ad esempio gli attributi tema ?attr/colorSurface e ?attr/colorOnSurface, consente di accedere facilmente ai 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. Di seguito sono riportate le opzioni consigliate:

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

Queste opzioni corrispondono direttamente alle modalità 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 della tua app. In questo modo il sistema abbina il tema durante la schermata iniziale.

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

Tema scuro forzato

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

La modalità Forza 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 modalità Sfondo obbligatoria e implementazione nativa per ridurre il tempo necessario per implementare il tema scuro.

Le app devono attivare il tema scuro forzato 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 la modalità Forza scuro, testa l'app con attenzione ed escludi le visualizzazioni in base alle esigenze.

Se la tua app utilizza un tema scuro, ad esempio Theme.Material, la modalità Forza scuro non viene applicata. Analogamente, se il tema dell'app eredita un tema DayNight, Forza tema scuro non viene applicato a causa del cambio automatico del tema.

Disattivare la modalità Forza Buio in una visualizzazione

La modalità Scura forzata può essere controllata in visualizzazioni specifiche con l'attributo layout android:forceDarkAllowed 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 interfacce utente visualizzate sul dispositivo, ma che non controlli direttamente, assicurati che le visualizzazioni utilizzate riflettano il tema dell'app host. Due esempi sono le notifiche e i widget Avvio app.

Notifiche

Utilizza i modelli di notifica forniti dal sistema, ad esempio MessagingStyle. Ciò significa che è il sistema a occuparsi di applicare lo stile corretto alla visualizzazione.

Widget e visualizzazioni di notifiche personalizzate

Per i widget del programma di avvio o se la tua app utilizza visualizzazioni dei contenuti delle notifiche personalizzate, effettua il test dei contenuti sia con il tema chiaro che con quello scuro.

Ecco alcuni errori comuni da tenere in considerazione:

• Supponendo che il colore di sfondo sia sempre chiaro.
• Colori di testo hardcoded.
• Impostazione di un colore di sfondo hardcoded con il colore di testo predefinito.
• Utilizzo di un'icona drawable di colore statico.

In tutti questi casi, utilizza attributi tematici appropriati anziché colori hardcoded.

Schermate di lancio

Se la tua app ha una schermata di avvio personalizzata, potresti doverla modificare in modo che rifletta il tema selezionato.

Rimuovi eventuali colori hardcoded, ad esempio i colori di sfondo impostati tramite programmazione su bianco. Utilizza invece l'attributo tema ?android:attr/colorBackground.

Modifiche alla configurazione

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

In alcuni casi, potresti volere che la modifica della configurazione venga gestita da un'app. Ad esempio, potresti voler ritardare una modifica di 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 suo metodo onConfigurationChanged() viene chiamato in caso di modifica del tema.

Per controllare il tema corrente, 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;
}