Tema escuro

O tema escuro está disponível no Android 10 (nível de API 29) e em versões posteriores. Ele tem diversos benefícios:

• É capaz de reduzir o uso de energia em uma quantidade significativa (dependendo da tecnologia da tela do dispositivo).
• Melhora a visibilidade para usuários com problemas de visão e que tenham sensibilidade ao brilho da luz.
• Facilita que o dispositivo seja usado por todos em um ambiente de pouca luz.

O tema escuro se aplica à IU do sistema Android e aos aplicativos que operam no dispositivo.

Há três maneiras de ativar o tema escuro no Android 10 (nível de API 29) e em versões posteriores:

• Usar a configuração do sistema (Configurações -> Tela -> Tema) para ativar o tema escuro.
• Usar o bloco de configurações rápidas para trocar os temas na bandeja de notificação (após a ativação).
• Em dispositivos Pixel, ao selecionar o modo Economia de bateria, o tema escuro é ao mesmo tempo ativado. Outros OEMs podem ou não oferecer suporte a esse comportamento.

Compatibilidade com o tema escuro no seu aplicativo

Para ter compatibilidade com o tema escuro, você precisa configurar o tema do seu aplicativo (normalmente 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 do MaterialComponents:

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

Isso vincula o tema principal do aplicativo aos sinalizadores do modo noturno controlado pelo sistema e oferece ao aplicativo um tema escuro padrão (quando ativado).

Temas e estilos

Nos seus temas e estilos, evite usar cores ou ícones codificados para uso em um tema claro. Em vez disso, use atributos de tema (de preferência) ou recursos qualificados para a noite.

Estes são os dois atributos de tema mais importantes:

• ?android:attr/textColorPrimary Trata-se de uma cor de texto de uso geral. Quase preto no tema claro e quase branco nos temas escuros. Ele contém um estado desativado.
• ?attr/colorControlNormal É uma cor de ícone de uso geral. Ele contém um estado desativado.

Recomendamos o uso de componentes do Material Design. Eles têm um sistema de temas coloridos (como os atributos do tema ?attr/colorSurface e ?attr/colorOnSurface) que oferece fácil acesso a cores adequadas. Obviamente, esses atributos podem ser personalizados no seu tema.

Alteração de temas no aplicativo

Pode ser que você queira permitir que os usuários alterem o tema do aplicativo durante a execução. Seu aplicativo pode deixar que o usuário escolha entre os temas.

Ao executar em dispositivos que operam no Android 9 ou versões anteriores, estas são as opções de tema recomendadas:

• Claro
• Escuro
• Definido pela Economia de bateria (a opção padrão recomendada)

Ao operar no Android 10 (nível de API 29) e em versões posteriores, as opções recomendadas são diferentes para permitir que o usuário modifique o padrão do sistema:

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

Caso o usuário selecione o tema claro e, em seguida, a Economia de bateria, a configuração não será alterada.

Cada opção mapeia diretamente a um dos modos AppCompat.DayNight:

• Claro: MODE_NIGHT_NO
• Escuro: MODE_NIGHT_YES
• Definido pela Economia de bateria: MODE_NIGHT_AUTO_BATTERY
• Padrão do sistema: MODE_NIGHT_FOLLOW_SYSTEM

Para trocar o tema, chame AppCompatDelegate.setDefaultNightMode().

Force Dark

O Android 10 oferece o Force Dark, um recurso para desenvolvedores implementarem rapidamente um tema escuro sem configurar um tema DayNight de forma explícita, como descrito acima.

O Force Dark analisa cada visualização do seu aplicativo com tema claro e aplica automaticamente um tema escuro antes de ele ser desenhado na tela. Alguns desenvolvedores usam uma combinação do Force Dark e da implementação nativa para reduzir o tempo necessário para implementar o tema escuro.

Os aplicativos precisam ativar o Force Dark por meio da configuração de android:forceDarkAllowed="true" no tema do aplicativo. Esse atributo é definido em todos os temas claros fornecidos pelo sistema e pelo AndroidX, como Theme.Material.Light. Ao usar o Force Dark, teste minuciosamente seu aplicativo e exclua as visualizações conforme necessário.

Caso o aplicativo use um tema escuro (como Theme.Material), o Force Dark não será aplicado. De modo semelhante, se o tema do aplicativo for herdado de um tema DayNight, o Force Dark não será aplicado, devido à troca automática de temas.

Como desativar o Force Dark em uma visualização

O Force Dark pode ser controlado em visualizações específicas com atributo de layout android:forceDarkAllowed ou com setForceDarkAllowed().

Práticas recomendadas

Notificações e widgets

Para superfícies de IU que você exibe no dispositivo, mas que não controla diretamente, é importante verificar se as visualizações usadas refletem o tema do aplicativo host. Dois bons exemplos são as notificações e os widgets na 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 garantir que o estilo de visualização correto está aplicado.

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

Para os widgets na tela de início ou caso o aplicativo use visualizações de conteúdo de notificação personalizado, é importante testar o conteúdo nos temas claro e escuro.

Tome cuidado com os erros mais comuns:

• Supor que a cor em segundo plano seja sempre clara
• Codificar as cores do texto
• Configurar uma cor em segundo plano codificada e usar a cor de texto padrão ao mesmo tempo
• Usar um ícone drawable que seja uma cor estática

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

Telas de inicialização

Caso seu aplicativo tenha uma tela de inicialização personalizada, pode ser necessário que ela seja modificada para refletir o tema selecionado.

Remova todas as cores codificadas. Por exemplo, todas as cores brancas em segundo plano. Em vez disso, use o atributo de tema ?android:attr/colorBackground.

Os drawables android:windowBackground de tema escuro só funcionam no Android Q.

Alterações de configuração

Quando o tema do aplicativo é alterado (pela configuração do sistema ou pelo AppCompat), uma alteração da configuração uiMode é acionada. Isso significa que as atividades serão recriadas automaticamente.

Em alguns casos, convém que um aplicativo gerencie a alteração da configuração. Por exemplo, você pode querer atrasar a alteração de uma configuração devido à reprodução de um vídeo.

Um aplicativo pode gerenciar a implementação do tema escuro por si só. Para isso, ele precisa declarar que cada atividade é capaz de processar a alteração da configuração uiMode:

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

Quando uma atividade declarar que pode gerenciar as alterações de configuração, o método onConfigurationChanged() dela será chamado no momento em que houver uma mudança de tema.

Para verificar qual o tema atual, os aplicativos podem executar um código como este:

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