Configurar de ponta a ponta

A exibição de ponta a ponta permite que o app mostre a interface por trás das barras de sistema (barra de status, barra de legenda e barra de navegação) para oferecer uma experiência do usuário mais imersiva. Se você segmentar dispositivos com Android 15 (nível 35 da API) ou mais recente, o modo de ponta a ponta será aplicado por padrão.

Para mostrar o conteúdo de ponta a ponta corretamente em todas as versões do Android, siga estas etapas de configuração. Sem essas etapas, o app pode renderizar cores sólidas atrás das barras de sistema ou não animar o conteúdo de forma síncrona com as transições do teclado na tela (IME).

1. Ativar a exibição de ponta a ponta

Para ativar o modo de ponta a ponta em versões anteriores do Android, chame enableEdgeToEdge() no método Activity.onCreate():

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    ...
}

Por padrão, o enableEdgeToEdge() torna as barras de sistema transparentes, exceto no modo de navegação com três botões, em que aplica uma máscara translúcida à barra de navegação para melhorar o contraste. A cor dos ícones do sistema e do scrim se adapta ao tema claro ou escuro do sistema.

2. Configurar windowSoftInputMode

Defina android:windowSoftInputMode="adjustResize" na entrada AndroidManifest.xml da sua atividade. Essa configuração permite que seu app receba encartes de IME, permitindo ajustar o layout com padding quando o teclado na tela aparece ou desaparece.

<!-- In your AndroidManifest.xml file: -->
<activity
  android:name=".ui.MainActivity"
  android:label="@string/app_name"
  android:windowSoftInputMode="adjustResize"
  android:theme="@style/Theme.MyApplication"
  android:exported="true">
  ...
</activity>

3. Processar sobreposições usando encartes

Depois que o modo de ponta a ponta é ativado, alguns elementos de conteúdo e da interface do app podem ser renderizados atrás das barras de sistema. Para evitar que elementos essenciais ou interativos sejam obscurecidos pelas barras de sistema ou se sobreponham a gestos do sistema, é necessário processar encartes.

As margens descrevem partes da tela que se cruzam com a interface do sistema ou com gestos do sistema. Os principais tipos de margens a serem considerados para exibição de ponta a ponta são:

• Encartes de barras de sistema:representam áreas onde as barras de sistema são exibidas. Use-as para evitar que a interface seja obscurecida pelas barras de sistema.
• Encaixes de corte da tela:representam áreas em que há um corte físico (como um entalhe de câmera) na tela do dispositivo.

No Compose, é possível processar encartes usando réguas, modificadores de padding ou modificadores de tamanho de encarte. Consulte Sobre encartes de janela para orientações detalhadas.

Tópicos avançados

Considere o seguinte para casos de uso mais avançados de ponta a ponta.

Modo imersivo

Alguns conteúdos, como vídeos ou mapas, se beneficiam de uma experiência totalmente imersiva em que as barras de sistema ficam ocultas. Você pode ocultar as barras de sistema usando WindowInsetsControllerCompat:

val windowInsetsController =
    WindowCompat.getInsetsController(window, window.decorView)

// Hide the system bars.
windowInsetsController.hide(WindowInsetsCompat.Type.systemBars())

// Show the system bars.
windowInsetsController.show(WindowInsetsCompat.Type.systemBars()) For example, use either `Scaffold`,

Cores e ícones da barra de sistema

Ao ir de ponta a ponta, o plano de fundo do app pode ficar visível atrás das barras de sistema. Por isso, talvez seja necessário ajustar as cores dos ícones da barra de sistema para melhorar o contraste.

Para mudar os ícones da barra de status para claro ou escuro, use WindowInsetsControllerCompat:

// Set status bar icons to dark
WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = true

// Set status bar icons to light
WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = false

Proteção da barra de sistema

Embora o enableEdgeToEdge() forneça barras de sistema transparentes ou translúcidas por padrão, talvez seja necessário personalizar isso. Consulte as diretrizes de design das barras de sistema do Android e de design de ponta a ponta para decidir quando usar barras transparentes ou translúcidas.

Para deixar a barra de navegação com três botões totalmente transparente em vez de translúcida, desative a imposição de contraste:

window.isNavigationBarContrastEnforced = false

Para mais informações, consulte Sobre a proteção da barra de sistema.

Caixas de diálogo

Para mostrar caixas de diálogo em tela cheia de ponta a ponta, chame WindowCompat.enableEdgeToEdge no método onStart() da caixa de diálogo:

class MyAlertDialogFragment : DialogFragment() {
    override fun onStart(){
        super.onStart()
        dialog?.window?.let { WindowCompat.enableEdgeToEdge(it) }
    }
    ...
}