Implementare il tema scuro

Prova la modalità Scrivi

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

Schema 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 sensibili alla luce intensa.
• Semplifica l'utilizzo del dispositivo in un ambiente poco illuminato.

Il tema scuro viene applicato all'UI 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 dalla barra delle notifiche, se abilitato.
• 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 a contenuti basati sul web utilizzando un componente WebView, consulta Scurire i contenuti web in WebView.

Supporto del tema scuro nell'app

Per supportare il tema scuro, imposta il tema dell'app, generalmente 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 di Material Componenti:

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

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

Temi e stili

Evita di utilizzare icone o colori impostati come hardcoded in un tema chiaro. Usa invece gli attributi del tema o le risorse idonee alla notte.

I due attributi del tema sono più importanti per il tema scuro:

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

Ti consigliamo di utilizzare i componenti di Material Design, poiché il relativo sistema di temi cromatici, come gli attributi del tema ?attr/colorSurface e ?attr/colorOnSurface, consente di accedere facilmente ai colori adatti. Puoi personalizzare questi attributi nel tema.

Modificare i temi nell'app

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

• Leggero
• Scuro
• Predefinita di sistema (opzione predefinita consigliata)

Queste opzioni corrispondono direttamente alle modalità AppCompat.DayNight:

• Leggero: MODE_NIGHT_NO.

• Scuro: MODE_NIGHT_YES.

• Predefinito di sistema: MODE_NIGHT_FOLLOW_SYSTEM.

Per cambiare tema:

• A livello API 31 e livelli successivi, utilizza UiModeManager#setApplicationNightMode per comunicare al sistema il tema eseguito dalla tua app. Ciò consente al sistema di associare il tema alla schermata iniziale.

• A livello API 30 e livelli 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.

Forza Buio analizza ogni visualizzazione della tua app a tema chiaro e applica automaticamente un tema scuro prima che venga attirato sullo schermo. Puoi utilizzare una combinazione di implementazione Force Dark e nativa per ridurre il tempo necessario per implementare il tema scuro.

Per le app è necessario attivare la modalità Buio forzato impostando android:forceDarkAllowed="true" nel tema dell'attività. Questo attributo è impostato su tutti i temi leggeri forniti dal sistema e AndroidX, come Theme.Material.Light. Quando utilizzi Forza scuro, testa la tua app a fondo ed escludi le visualizzazioni in base alle necessità.

Se la tua app utilizza un tema scuro, ad esempio Theme.Material, l'opzione Forza scuro non viene applicata. Allo stesso modo, se il tema dell'app eredita da un tema DayNight, l'opzione Forza scura non viene applicata perché il tema viene cambiato automaticamente.

Disattivare la modalità Buio forzato in una visualizzazione

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, vedi Scurire i contenuti web in WebView. Per un esempio di tema scuro applicato a un componente WebView, vedi la demo di WebView su GitHub.

Best practice

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

Notifiche e widget

Per le piattaforme UI che mostri 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 Avvio app.

Notifiche

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

Widget e visualizzazioni di notifiche personalizzate

Per i widget Avvio app o se la tua app utilizza visualizzazioni personalizzate di contenuti delle notifiche, testa i contenuti su entrambi i temi chiaro e scuro.

Ecco alcuni problemi comuni da tenere a mente:

• Supponendo che il colore di sfondo sia sempre chiaro.
• Colori del testo hardcoded.
• Impostazione di un colore di sfondo impostato come hardcoded utilizzando il colore di testo predefinito.
• Utilizzo di un'icona disegnabile di colore statico.

In tutti questi casi, utilizza attributi del tema appropriati anziché colori impostati come hardcoded.

Schermate di avvio

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

Rimuovi tutti i colori impostati come hardcoded, come i colori di sfondo impostati in modo programmatico sul 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, attiva una modifica della configurazione di uiMode. Ciò significa che le attività vengono ricreate automaticamente.

In alcuni casi, potresti volere che un'app gestisca 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 alla configurazione di uiMode:

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

Quando un oggetto Activity dichiara di gestire le modifiche alla configurazione, il suo metodo onConfigurationChanged() viene chiamato in caso di modifica del tema.

Per controllare qual è 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;
}