Implementar o tema escuro

Experimente trabalhar com o Compose
O Jetpack Compose é o kit de ferramentas de IU recomendado para Android. Saiba como trabalhar com temas no Compose.
Esquema de cores: Material Design 3 →

Figura 1. Tema escuro.

O tema escuro está disponível no Android 10 (API de nível 29) e versões mais recentes. Ele tem os seguintes benefícios:

  • Reduz significativamente o consumo de energia, dependendo da tecnologia da tela do dispositivo.
  • Melhora a visibilidade para usuários com baixa visão e para aqueles sensíveis a luzes intensas.
  • Facilita o uso do dispositivo em ambientes com pouca luz.

O tema escuro se aplica à interface do sistema Android e aos apps em execução no dispositivo.

Há três maneiras de ativar o tema escuro no Android 10 e versões mais recentes:

  • Use a configuração do sistema em Configurações > Tela > Tema para ativar o tema escuro.
  • Use o bloco de Configurações Rápidas para alternar entre os temas na bandeja de notificações, quando ativado.
  • Em dispositivos Pixel, ative o modo de economia de bateria para ativar o tema escuro ao mesmo tempo. Outros dispositivos podem não ser compatíveis com esse comportamento.

Para ver instruções sobre como aplicar um tema escuro ao conteúdo baseado na Web usando um componente WebView, consulte Escurecer conteúdo da Web com WebView.

Oferecer compatibilidade com o tema escuro no app

Para oferecer suporte ao tema escuro, defina o tema do app, geralmente encontrado em res/values/styles.xml, para herdar de um tema DayNight:

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

Também é possível usar o tema escuro dos componentes do Material Design:

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

Isso vincula o tema principal do app às flags do modo noturno controladas pelo sistema e fornece ao app um tema escuro padrão quando ele é ativado.

Temas e estilos

Evite usar cores ou ícones fixados no código destinados a um tema claro. Em vez disso, use atributos de tema ou recursos qualificados para o modo noturno.

Dois atributos de tema são mais importantes para o tema escuro:

  • ?android:attr/textColorPrimary: uma cor de texto de uso geral. Ela é quase preta no tema claro e quase branca no tema escuro. Contém um estado desativado.
  • ?attr/colorControlNormal: uma cor de ícone de uso geral. Contém um estado desativado.

Recomendamos o uso de componentes do Material Design, já que o sistema de temas de cores, como os atributos de tema ?attr/colorSurface e ?attr/colorOnSurface, oferece acesso fácil a cores adequadas. É possível personalizar esses atributos no seu tema.

Mudar temas no app

Você pode permitir que os usuários mudem o tema do app enquanto ele está em execução. As seguintes são opções recomendadas:

  • Claro
  • Escuro
  • Padrão do sistema (a opção padrão recomendada)

Essas opções são mapeadas diretamente para os modos AppCompat.DayNight:

Para mudar o tema, faça o seguinte:

Forçar modo escuro

O Android 10 oferece o recurso Forçar tema escuro, que permite aos desenvolvedores implementar rapidamente um tema escuro sem definir explicitamente um tema DayNight.

O recurso Forçar Tema Escuro analisa cada visualização do seu app com tema claro e aplica um tema escuro automaticamente antes de ser renderizado na tela. É possível usar uma combinação de Forçar tema escuro e implementação nativa para reduzir o tempo necessário para implementar o tema escuro.

Os apps precisam ativar o recurso Forçar Tema Escuro definindo android:forceDarkAllowed="true" no tema da atividade. Esse atributo é definido em todos os temas claros fornecidos pelo sistema e pelo AndroidX, como Theme.Material.Light. Ao usar o recurso Forçar tema escuro, teste seu app completamente e exclua as visualizações conforme necessário.

Se o app usar um tema escuro, como Theme.Material, o recurso Forçar Tema Escuro não será aplicado. Da mesma forma, se o tema do app herdar de um tema DayNight, o recurso Forçar Tema Escuro não será aplicado devido à troca automática de tema.

Desativar o Forçar modo escuro em uma visualização

O recurso Forçar tema escuro pode ser controlado em visualizações específicas com o atributo de layout android:forceDarkAllowed ou com setForceDarkAllowed().

Conteúdo da Web

Para ver informações sobre como usar temas escuros no conteúdo baseado na Web, consulte Escurecer conteúdo da Web com WebView. Para ver um exemplo de tema escuro aplicado a uma WebView, consulte a demonstração da WebView no GitHub .

Práticas recomendadas

As seções a seguir demonstram as práticas recomendadas para implementar temas escuros.

Notificações e widgets

Para as plataformas de interface que você mostra no dispositivo, mas não controla diretamente, verifique se as visualizações usadas refletem o tema do app host. Dois exemplos são as notificações e os widgets da tela de início.

Notificações

Use os modelos de notificação fornecidos pelo sistema, como MessagingStyle. Isso significa que o sistema é responsável por aplicar o estilo de visualização correto.

Widgets e visualizações de notificações personalizadas

Para widgets de tela de início ou se o app usa visualizações de conteúdo de notificação personalizadas, teste o conteúdo nos temas claro e escuro.

Confira alguns erros comuns:

  • Supondo que a cor do plano de fundo seja sempre clara.
  • Fixar cores do texto no código.
  • Definir uma cor de plano de fundo codificada ao usar a cor de texto padrão.
  • Usar um ícone drawable com uma cor estática.

Em todos esses casos, use atributos de tema adequados em vez de cores codificadas.

Telas de inicialização

Se o app tiver uma tela de inicialização personalizada, talvez seja necessário modificá-la para que ela reflita o tema selecionado.

Remova todas as cores fixadas no código, como as cores de plano de fundo definidas de forma programática como branco. Use o atributo de tema ?android:attr/colorBackground.

Alterações de configuração

Quando o tema do app muda, seja pela configuração do sistema ou pelo AppCompat, isso aciona uma mudança de configuração uiMode. Isso significa que as atividades são recriadas automaticamente.

Em alguns casos, pode ser interessante que um app processe a mudança de configuração. Por exemplo, é recomendável atrasar uma mudança de configuração quando um vídeo está sendo exibido.

Um app pode processar a implementação do tema escuro declarando que cada Activity pode processar a mudança de configuração uiMode:

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

Quando uma Activity declara que processa mudanças de configuração, o método onConfigurationChanged() é chamado quando há uma mudança de tema.

Para verificar qual é o tema atual, os apps podem executar códigos como este:

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