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 a renderização de ponta a ponta é ativada, alguns elementos de conteúdo e da interface do app podem ser renderizados atrás das barras de sistema. Para evitar que elementos críticos ou interativos sejam obscurecidos por 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 encartes 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.

Temas 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. É possível 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 das barras 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) }
    }
    ...
}