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

Supporto del 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 Material Components:

<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 assegnato all'app un tema scuro predefinito quando è attivo.

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 del testo generico. È quasi nero nel tema chiaro e quasi bianco nei temi scuri. Contiene uno stato disabilitato.
• ?attr/colorControlNormal: un colore dell'icona per uso 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 cambiare il tema dell'app mentre questa è 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 Scuro forzato, 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 impostazione Forza scuro 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 AndroidX, ad esempio Theme.Material.Light. Quando utilizzi Force Dark, testa l'app a fondo ed escludi le visualizzazioni in base alle necessità.

Se la tua app utilizza un tema scuro, come Theme.Material, non viene applicata la funzionalità Scuro forzato. 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

L'opzione Scuro forzato può essere controllata su viste specifiche con l'attributo di layout android:forceDarkAllowed o con setForceDarkAllowed().

Contenuti web

Per informazioni sull'utilizzo dei temi scuri nei contenuti web, consulta Oscurare i contenuti web in WebView. Per un esempio di tema scuro applicato a un componente WebView, guarda 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 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, testa i contenuti sia con il tema chiaro che con quello scuro.

Gli insidie più comuni da tenere presenti sono:

• 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 rispecchia 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, attiva una modifica della configurazione di uiMode. Ciò significa che le attività vengono ricreate automaticamente.

In alcuni casi, potresti volere che sia un'app a gestire la modifica della configurazione. 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;
}