Mostre conteúdo de ponta a ponta no app e processe encartes de janela no Compose

A plataforma Android é responsável por desenhar a interface do sistema, como a barra de status e a barra de navegação. Essa interface do sistema é exibida independentemente do app que o usuário está usando.

WindowInsets fornece informações sobre a interface do sistema para garantir que o app seja renderizado na área correta e que a interface não seja obscurecida pela interface do sistema.

No Android 14 (nível 34 da API) e versões anteriores, a interface do app não é renderizada abaixo das barras de sistema e dos cortes de tela por padrão.

No Android 15 (nível 35 da API) e versões mais recentes, o app é renderizado abaixo das barras do sistema e exibe recortes quando o app é direcionado ao SDK 35. Isso resulta em uma experiência do usuário mais integrada e permite que o app aproveite ao máximo o espaço da janela disponível.

A exibição de conteúdo atrás da IU do sistema é chamada de exibição de ponta a ponta. Nesta página, você vai aprender sobre os diferentes tipos de insets, como ir de borda a borda, e como usar as APIs inset para animar a interface e garantir que o conteúdo do app não seja obscurecido por elementos da interface do sistema.

Conceitos básicos de inserção

Quando um app é exibido de ponta a ponta, é necessário garantir que o conteúdo e as interações importantes não sejam obscurecidos pela interface do sistema. Por exemplo, se um botão for colocado atrás da barra de navegação, o usuário não poderá clicar nele.

O tamanho da interface do sistema e as informações sobre onde ela é colocada são especificados por insets.

Cada parte da interface do sistema tem um tipo correspondente de inseto que descreve o tamanho e o local em que ele é colocado. Por exemplo, os encartes da barra de status fornecem o tamanho e a posição da barra de status, enquanto os encartes da barra de navegação fornecem o tamanho e a posição da barra de navegação. Cada tipo de inseto consiste em quatro dimensões de pixel: superior, esquerda, direita e inferior. Essas dimensões especificam até onde a interface do sistema se estende dos lados correspondentes da janela do app. Para evitar a sobreposição com esse tipo de interface do sistema, a interface do app precisa ser inserida nesse valor.

Estes tipos de inset integrados do Android estão disponíveis no WindowInsets:

Esses tipos são resumidos por três tipos de inserção "seguros" que garantem que o conteúdo não seja obstruído:

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

Esses tipos de insetos "seguros" protegem o conteúdo de maneiras diferentes, com base nos insetos da plataforma:

• Use WindowInsets.safeDrawing para proteger o conteúdo que não pode ser exibido abaixo de nenhuma interface do sistema. Esse é o uso mais comum de insets: evitar a exibição de conteúdo obscurecido pela interface do sistema (parcial ou completamente).
• Use WindowInsets.safeGestures para proteger o conteúdo com gestos. Isso evita que os gestos do sistema entrem em conflito com os gestos do app (como os de páginas inferiores, carrosséis ou jogos).
• Use WindowInsets.safeContent como uma combinação de WindowInsets.safeDrawing e WindowInsets.safeGestures para garantir que o conteúdo não tenha sobreposição visual nem de gestos.

Configuração de encartes

Para permitir que o app tenha controle total sobre onde ele extrai conteúdo, siga estas etapas de configuração. Sem essas etapas, o app pode desenhar cores pretas ou sólidas atrás da interface do sistema ou não animar de forma síncrona com o teclado do software.

1. Segmente o SDK 35 ou mais recente para forçar a tela cheia no Android 15 e versões mais recentes. O app é exibido atrás da interface do sistema. É possível ajustar a interface do app processando insets.
2. Se preferir, chame enableEdgeToEdge() em Activity.onCreate(), que permite que o app seja exibido de ponta a ponta em versões anteriores do Android.

3. Defina android:windowSoftInputMode="adjustResize" na entrada AndroidManifest.xml da atividade. Essa configuração permite que o app receba o tamanho do IME do software como insets, que podem ser usados para preencher e posicionar o conteúdo adequadamente quando o IME aparece e desaparece no app.

   <!-- 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">
   

APIs Compose

Depois que a atividade assumir o controle de todos os insets, você poderá usar as APIs do Compose para garantir que o conteúdo não seja obscurecido e que os elementos interativos não se sobreponham à interface do sistema. Essas APIs também sincronizam o layout do app com as mudanças de engaste.

Por exemplo, este é o método mais básico de aplicar os insets ao conteúdo de todo o app:

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

    enableEdgeToEdge()

    setContent {
        Box(Modifier.safeDrawingPadding()) {
            // the rest of the app
        }
    }
}
InsetsSnippets.kt

Esse snippet aplica os encartes de janela safeDrawing como padding em todo o conteúdo do app. Embora isso garanta que os elementos interativos não se sobreponham à interface do sistema, também significa que nenhum elemento do app será exibido atrás da interface do sistema para alcançar um efeito de borda a borda. Para aproveitar toda a janela, você precisa ajustar onde os insets são aplicados em cada tela ou componente.

Todos esses tipos de inseto são animados automaticamente com animações de IME reportadas para a API 21. Por extensão, todos os layouts que usam esses insets também são animados automaticamente conforme os valores de inset mudam.

Há duas maneiras principais de usar esses tipos de inseto para ajustar os layouts do elemento combinável: modificadores de padding e modificadores de tamanho de inseto.

Modificadores de padding

Modifier.windowInsetsPadding(windowInsets: WindowInsets) aplica os insets de janela fornecidos como padding, agindo exatamente como Modifier.padding. Por exemplo, Modifier.windowInsetsPadding(WindowInsets.safeDrawing) aplica os engastes de desenho seguros como padding nos quatro lados.

Há também vários métodos utilitários integrados para os tipos de inset mais comuns. Modifier.safeDrawingPadding() é um desses métodos, equivalente a Modifier.windowInsetsPadding(WindowInsets.safeDrawing). Há modificadores análogos para os outros tipos de inset.

Modificadores de tamanho de inserção

Os modificadores a seguir aplicam uma quantidade de engastes de janela definindo o tamanho do componente como o tamanho dos engastes:

Esses modificadores são especialmente úteis para dimensionar um Spacer que ocupa o espaço de insets:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

Consumo de Inset

Os modificadores de padding de inserção (windowInsetsPadding e auxiliares como safeDrawingPadding) consomem automaticamente a parte dos insets que são aplicadas como padding. Ao se aprofundar na árvore de composição, os modificadores de padding anexados e os modificadores de tamanho de inseto sabem que parte dos insetos já foi consumida por modificadores de padding externos e evitam usar a mesma parte dos insetos mais de uma vez, o que resultaria em muito espaço extra.

Os modificadores de tamanho de inseto também evitam usar a mesma parte de insetos mais de uma vez se os insetos já foram consumidos. No entanto, como eles estão mudando o tamanho diretamente, eles não consomem insets.

Como resultado, o aninhamento de modificadores de padding muda automaticamente a quantidade de padding aplicada a cada elemento combinável.

Analisando o mesmo exemplo de LazyColumn anterior, o LazyColumn está sendo redimensionado pelo modificador imePadding. Dentro do LazyColumn, o último item é dimensionado para ser a altura da parte de baixo das barras do sistema:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

Quando o IME está fechado, o modificador imePadding() não aplica padding, já que o IME não tem altura. Como o modificador imePadding() não está aplicando padding, nenhum inseto está sendo consumido, e a altura da Spacer será o tamanho da parte de baixo das barras do sistema.

Quando o IME é aberto, os insets são animados para corresponder ao tamanho do IME, e o modificador imePadding() começa a aplicar o padding inferior para redimensionar o LazyColumn quando o IME é aberto. À medida que o modificador imePadding() começa a aplicar o padding inferior, ele também começa a consumir essa quantidade de insets. Portanto, a altura do Spacer começa a diminuir, já que parte do espaçamento das barras do sistema já foi aplicado pelo modificador imePadding(). Quando o modificador imePadding() aplica um valor de padding inferior maior que as barras do sistema, a altura do Spacer é zero.

Quando o IME é fechado, as mudanças acontecem de forma inversa: o Spacer começa a se expandir a partir de uma altura de zero quando o imePadding() está aplicando menos que a parte de baixo das barras do sistema, até que o Spacer corresponda à altura da parte de baixo das barras do sistema quando o IME é completamente animado.

Esse comportamento é alcançado pela comunicação entre todos os modificadores windowInsetsPadding e pode ser influenciado de algumas outras maneiras.

Modifier.consumeWindowInsets(insets: WindowInsets) também consome encartes da mesma forma que Modifier.windowInsetsPadding, mas não aplica os encartes consumidos como padding. Isso é útil em combinação com os modificadores de tamanho de insetos, para indicar a elementos irmãos que uma determinada quantidade de insetos já foi consumida:

Column(Modifier.verticalScroll(rememberScrollState())) {
    Spacer(Modifier.windowInsetsTopHeight(WindowInsets.systemBars))

    Column(
        Modifier.consumeWindowInsets(
            WindowInsets.systemBars.only(WindowInsetsSides.Vertical)
        )
    ) {
        // content
        Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
    }

    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.systemBars))
}
InsetsSnippets.kt

O Modifier.consumeWindowInsets(paddingValues: PaddingValues) se comporta de maneira muito semelhante à versão com um argumento WindowInsets, mas consome um PaddingValues arbitrário. Isso é útil para informar elementos filhos quando o padding ou o espaçamento é fornecido por algum outro mecanismo que não seja os modificadores de padding de inserção, como um Modifier.padding comum ou espaçadores de altura fixa:

Column(Modifier.padding(16.dp).consumeWindowInsets(PaddingValues(16.dp))) {
    // content
    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
}
InsetsSnippets.kt

Nos casos em que os insetos de janela brutos são necessários sem consumo, use os valores de WindowInsets diretamente ou use WindowInsets.asPaddingValues() para retornar um PaddingValues dos insetos que não são afetados pelo consumo. No entanto, devido às ressalvas abaixo, prefira usar os modificadores de preenchimento e de tamanho de encartes de janela sempre que possível.

Insets e fases do Jetpack Compose

O Compose usa as APIs principais do AndroidX para atualizar e animar insets, que usam as APIs da plataforma para gerenciar insets. Devido a esse comportamento da plataforma, os insets têm uma relação especial com as fases do Jetpack Compose.

O valor dos insets é atualizado após a fase de composição, mas antes da fase de layout. Isso significa que a leitura do valor dos encartes na composição geralmente usa um valor dos encartes que está um frame atrasado. Os modificadores integrados descritos nesta página são criados para atrasar o uso dos valores dos insets até a fase de layout, o que garante que os valores de inset sejam usados no mesmo frame em que são atualizados.

Animações de IME do teclado com WindowInsets

É possível aplicar Modifier.imeNestedScroll() a um contêiner de rolagem para abrir e fechar o IME automaticamente ao rolar até a parte de baixo do contêiner.

class WindowInsetsExampleActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        WindowCompat.setDecorFitsSystemWindows(window, false)

        setContent {
            MaterialTheme {
                MyScreen()
            }
        }
    }
}

@OptIn(ExperimentalLayoutApi::class)
@Composable
fun MyScreen() {
    Box {
        LazyColumn(
            modifier = Modifier
                .fillMaxSize() // fill the entire window
                .imePadding() // padding for the bottom for the IME
                .imeNestedScroll(), // scroll IME at the bottom
            content = { }
        )
        FloatingActionButton(
            modifier = Modifier
                .align(Alignment.BottomEnd)
                .padding(16.dp) // normal 16dp of padding for FABs
                .navigationBarsPadding() // padding for navigation bar
                .imePadding(), // padding for when IME appears
            onClick = { }
        ) {
            Icon(imageVector = Icons.Filled.Add, contentDescription = "Add")
        }
    }
}
MigrationOtherConsiderationsSnippets.kt

Suporte a Inset para componentes do Material 3

Para facilitar o uso, muitos dos elementos combináveis integrados do Material 3 (androidx.compose.material3) processam os insetos por conta própria, com base em como os elementos combináveis são colocados no app de acordo com as especificações do Material.

Elementos combináveis de recuo

Confira abaixo uma lista dos componentes do Material Design que processam automaticamente os insets.

Barras de apps

• TopAppBar / SmallTopAppBar / CenterAlignedTopAppBar / MediumTopAppBar / LargeTopAppBar: aplica os lados superior e horizontal das barras do sistema como padding, já que é usado na parte de cima da janela.
• BottomAppBar: aplica os lados inferior e horizontal das barras do sistema como padding.

Contêineres de conteúdo

• ModalDrawerSheet / DismissibleDrawerSheet / PermanentDrawerSheet (conteúdo dentro de uma gaveta de navegação modal): aplica engastes vertical e start ao conteúdo.
• ModalBottomSheet: aplica os insetos inferiores.
• NavigationBar : aplica os engastes inferior e horizontal.
• NavigationRail: aplica os engastes vertical e start.

Scaffold

Por padrão, Scaffold fornece insets como parâmetro paddingValues para você consumir e usar. O Scaffold não aplica os insetos ao conteúdo. Essa responsabilidade é sua. Por exemplo, para consumir esses insetos com um LazyColumn dentro de um Scaffold:

Scaffold { innerPadding ->
    // innerPadding contains inset information for you to use and apply
    LazyColumn(
        // consume insets as scaffold doesn't do it by default
        modifier = Modifier.consumeWindowInsets(innerPadding),
        contentPadding = innerPadding
    ) {
        items(count = 100) {
            Box(
                Modifier
                    .fillMaxWidth()
                    .height(50.dp)
                    .background(colors[it % colors.size])
            )
        }
    }
}
InsetsSnippets.kt

Substituir insetos padrão

Você pode mudar o parâmetro windowInsets transmitido ao elemento combinável para configurar o comportamento dele. Esse parâmetro pode ser um tipo diferente de janela inserida para aplicar ou desativado transmitindo uma instância vazia: WindowInsets(0, 0, 0, 0).

Por exemplo, para desativar o processamento de insetos em LargeTopAppBar, defina o parâmetro windowInsets como uma instância vazia:

LargeTopAppBar(
    windowInsets = WindowInsets(0, 0, 0, 0),
    title = {
        Text("Hi")
    }
)
InsetsSnippets.kt

Interoperabilidade com os engastes do sistema de visualização

Se o app tiver códigos do Compose e da View, talvez seja necessário especificar explicitamente quais encartes do sistema cada um deles precisa consumir e garantir que os encartes sejam enviados para visualizações irmãs.

Como modificar os insetos padrão

Talvez seja necessário substituir os insets padrão quando a tela tiver visualizações e código do Compose na mesma hierarquia. Nesse caso, é necessário especificar qual deles deve consumir os insetos e qual deve ignorá-los.

Por exemplo, se o layout mais externo for um layout de visualização do Android, consuma os insets no sistema de visualização e ignore-os para o Compose. Como alternativa, se o layout mais externo for um elemento combinável, consuma as informações em Compose e adicione os elementos combináveis AndroidView.

Por padrão, cada ComposeView consome todos os insets no nível de consumo WindowInsetsCompat. Para mudar esse comportamento padrão, defina ComposeView.consumeWindowInsets como false.

Envio de insetos compatível com versões anteriores para visualizações

Se o app tiver código de visualizações, talvez seja necessário confirmar se os insets são enviados para visualizações irmãs em dispositivos com Android 10 (nível 29 da API) ou versões anteriores. Consulte o guia de visualizações de borda a borda para mais informações.

Ícones da barra do sistema

A chamada de enableEdgeToEdge garante que as cores do ícone da barra do sistema sejam atualizadas quando o tema do dispositivo mudar.

Ao usar a tela de uma borda à outra, talvez seja necessário atualizar manualmente as cores do ícone da barra do sistema para que elas contrastem com o plano de fundo do app. Por exemplo, para criar ícones de barra de status claros:

WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = false

WindowCompat.getInsetsController(window, window.getDecorView())
    .setAppearanceLightStatusBars(false);

Proteção da barra de sistema

Quando o app é direcionado ao SDK 35 ou mais recente, o preenchimento de tela é aplicado. A barra de status do sistema e as barras de navegação por gestos são transparentes, mas a barra de navegação com três botões é translúcida.

Para remover a proteção em segundo plano padrão da navegação com três botões, defina Window.setNavigationBarContrastEnforced como false.

Recursos

• Barra de sistema do Android: orientações de design da barra de sistema
• Now in Android: um app Android totalmente funcional criado com o Kotlin e o Jetpack Compose.
• Processar restrições de ponta a ponta no Android 15: um codelab que explica a restrição de ponta a ponta no Android 15.
• Dicas de processamento de insetos para a restrição de ponta a ponta do Android 15
• Visualizar e testar a interface de ponta a ponta do app
• 3 coisas para melhorar a experiência do seu app Android: Ponta a ponta, Volta preditiva e Resumo: um vídeo do YouTube sobre a aplicação do recurso Ponta a ponta do Android 15.
• Edge-to-edge and insets | Compose Tips: um vídeo do YouTube mostrando como lidar com insets para desenhar de borda a borda