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

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

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

Figura 1. Indo de ponta a ponta para desenhar atrás das barras do sistema.

No Android 14 (nível 34 da API) e versões anteriores, a interface do app não é renderizada abaixo das barras do 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 por trás da IU do sistema é chamada de de ponta a ponta. Neste você aprende sobre os diferentes tipos de encarte, como passar de ponta a ponta, e como usar as APIs de encarte para animar a interface e garantir que o conteúdo do app não seja ocultado por elementos da interface do sistema.

Importante: a ponta a ponta é aplicada no Android 15 e em versões mais recentes quando o app for direcionado SDK 35. Se o app ainda não ocupar toda a tela, partes dele podem estar escondidas, e você precisa processar os insets. Dependendo do app, esse trabalho pode ou não ser ou significativa. O componente Scaffold do Material 3 pode reduzir o trabalho necessário para ser compatível com a aplicação de borda a borda do Android 15. Consulte Criar um componente scaffold para manter a interface unida.

Princípios básicos do encarte

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 encarte que descreve o tamanho e onde é 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 encarte consiste em quatro dimensões em pixels: 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 sobreposta a esse tipo de interface do sistema. Portanto, a interface do app precisa ser inserida de dados.

Esses tipos de encarte integrados do Android estão disponíveis pelo WindowInsets:

WindowInsets.statusBars	Os insetos descrevem as barras de status. São as barras de interface do sistema na parte de cima que contêm ícones de notificação e outros indicadores.
WindowInsets.statusBarsIgnoringVisibility	Os engastes da barra de status quando eles estão visíveis. Se as barras de status estiverem ocultas (devido ao entrar no modo de tela cheia imersivo), os encartes da barra de status principal vão estar vazios, mas esses encartes não vão estar vazios.
WindowInsets.navigationBars	Os insetos descrevendo as barras de navegação. São as barras da interface do sistema no lado esquerdo, direito ou inferior do dispositivo, que descrevem a barra de tarefas ou os ícones de navegação. Eles podem mudar durante a execução com base no método de navegação preferido do usuário e na interação com a barra de tarefas.
WindowInsets.navigationBarsIgnoringVisibility	Os engastes da barra de navegação quando eles estão visíveis. Se as barras de navegação estiverem ocultas no momento (devido ao entrar no modo de tela cheia imersivo), os encartes da barra de navegação principal vão estar vazios, mas esses encartes não vão estar vazios.
WindowInsets.captionBar	O encarte descrevendo a decoração da janela da interface do sistema se estiver em uma janela de formato livre, como a barra de título superior.
WindowInsets.captionBarIgnoringVisibility	Os insetos da barra de legendas quando estão visíveis. Se as barras de legenda estiverem ocultas no momento, os encartes da barra de legenda principal estarão vazios, mas não estarão.
WindowInsets.systemBars	A união dos encartes da barra do sistema, que incluem as barras de status, de navegação e de legenda.
WindowInsets.systemBarsIgnoringVisibility	Os engastes da barra do sistema quando eles estão visíveis. Se as barras do sistema estiverem ocultas (por entrar no modo de tela cheia imersiva), os enfeites da barra principal do sistema vão estar vazios, mas não vão estar vazios.
WindowInsets.ime	Os encartes que descrevem a quantidade de espaço na parte inferior que o teclado de software ocupa.
WindowInsets.imeAnimationSource	Os insetos descrevem a quantidade de espaço que o teclado de software ocupava antes da animação atual.
WindowInsets.imeAnimationTarget	Os encartes que descrevem a quantidade de espaço que o teclado de software vai ocupar após a animação do teclado atual.
WindowInsets.tappableElement	Um tipo de encarte que descreve informações mais detalhadas sobre a interface de navegação, informando a quantidade de espaço em que o "toca" serão processados pelo sistema, não pelo aplicativo. Para barras de navegação transparentes com navegação por gestos, é possível tocar em alguns elementos do app na interface de navegação do sistema.
WindowInsets.tappableElementIgnoringVisibility	Os encartes de elemento tocável para quando ficam visíveis. Se os elementos tocáveis estiverem ocultos (devido ao entrar no modo de tela cheia imersivo), os encartes principais do elemento tocável vão estar vazios, mas esses encartes não vão estar.
WindowInsets.systemGestures	Os insets representam a quantidade de insets em que o sistema vai interceptar gestos para navegação. Os apps podem especificar manualmente o processamento de uma quantidade limitada desses gestos usando o Modifier.systemGestureExclusion.
WindowInsets.mandatorySystemGestures	Um subconjunto dos gestos do sistema que sempre serão gerenciados por ele e que não podem ser desativados pelo Modifier.systemGestureExclusion.
WindowInsets.displayCutout	Os insetos representam a quantidade de espaço necessária para evitar a sobreposição com um recorte de tela (entalhe ou orifício).
WindowInsets.waterfall	Os engastes que representam as áreas curvas de uma exibição em cascata. Uma tela em cascata tem áreas curvas ao longo das bordas, onde a tela começa a se curvar nas laterais do dispositivo.

Esses tipos são resumidos em três tipos de encarte que garantem que o conteúdo obscurecidos:

• 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. Este é o uso mais comum de encartes: para evitar mostrar conteúdo oculto pela interface do sistema (parcialmente 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 aplicativo (como os de baixo folhas, 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 desenha conteúdo, siga estas configurações etapas. Sem essas etapas, o app pode desenhar cores pretas ou sólidas por trás do interface do sistema ou não anime de forma síncrona com o teclado de software.

1. Direcione o SDK 35 ou mais recente para aplicar de ponta a ponta 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. Opcionalmente, chame enableEdgeToEdge() em Activity.onCreate(), o 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. Esta configuração permite que o app receba o tamanho do IME de software como encartes, que podem ser usados para preencher e posicionar o conteúdo quando o IME aparecer e desaparecer do 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 do Compose

Quando a atividade assumir o controle do processamento de todos os encartes, você poderá usar o Compose. APIs para garantir que o conteúdo não seja ofuscado e os elementos interativos não sejam se sobreponham à IU do sistema. Essas APIs também sincronizam o layout do app com as mudanças de inset.

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 ao máximo você precisa ajustar onde os encartes são aplicados em uma tela, tela por tela. ou componente por 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 seus layouts que usam esses encartes são também animados automaticamente à medida que os valores do encarte mudam.

Há duas maneiras principais de usar esses tipos de encarte para ajustar o elemento combinável. Layouts: modificadores de padding e modificadores de tamanho de encarte.

Modificadores de padding

Modifier.windowInsetsPadding(windowInsets: WindowInsets) aplica o encartes de janela fornecidos como padding, agindo da mesma forma que o Modifier.padding faria. Por exemplo, Modifier.windowInsetsPadding(WindowInsets.safeDrawing) se aplica o encarte seguro do desenho como padding nos quatro lados.

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

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:

Modifier.windowInsetsStartWidth(windowInsets: WindowInsets)	Aplica o lado inicial de windowInsets como a largura (como Modifier.width).
Modifier.windowInsetsEndWidth(windowInsets: WindowInsets)	Aplica o lado final de windowInsets como a largura (como Modifier.width).
Modifier.windowInsetsTopHeight(windowInsets: WindowInsets)	Aplica a parte de cima de windowInsets como a altura (como Modifier.height).
Modifier.windowInsetsBottomHeight(windowInsets: WindowInsets)	Aplica o lado inferior de windowInsets como a altura (como Modifier.height).

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 externo 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 encarte também evitam o uso da mesma parte de encartes mais de uma vez se os encartes já tiverem sido 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 de antes, o LazyColumn está sendo redimensionado pelo modificador imePadding. Dentro de LazyColumn, o último item é dimensionada para ser a altura da parte inferior 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 encarte será consumido, e a altura do Spacer será o tamanho do na 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.

Figura 2. Coluna lenta de borda a borda com TextField.

Cuidado: use Spacer em vez de contentPadding para desenhar o último TextField em um LazyColumn acima das barras do sistema. Caso contrário, o IME pode ocultar o TextField.

Esse comportamento é alcançado por meio da comunicação entre todas windowInsetsPadding e pode ser influenciada em alguns outros de várias formas.

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 junto com o encarte modificadores de tamanho para indicar a irmãos que uma certa quantidade de encartes já foi consumido:

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 muito semelhante à versão com um argumento WindowInsets, mas pega uma PaddingValues arbitrário para consumir. Isso é útil para informar filhos quando o preenchimento ou o espaçamento é fornecido por algum outro mecanismo além do Modificadores de encarte de padding, como um Modifier.padding comum ou uma altura fixa espaçadores:

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

Nos casos em que os encartes de janela brutos forem necessários sem consumo, use o método WindowInsets diretamente ou use WindowInsets.asPaddingValues() para retornar um PaddingValues dos encartes que não são afetados pelo consumo. No entanto, devido às ressalvas abaixo, prefira usar o padding de encartes de janela. e encarte 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. O modelo os modificadores descritos nesta página foram criados para atrasar o uso dos valores do elemento é inserido até a fase de layout, que garante que os valores de encarte sejam usados mesmo frame que são atualizados.

Animações do 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

Figura 3. Animações do IME.

Suporte a encarte para os componentes do Material 3

Para facilitar o uso, muitos dos elementos combináveis do Material 3 integrados (androidx.compose.material3) processar encartes 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.

Observação: componentes do Material 2 (androidx.compose.material) não processam automaticamente encartes. No entanto, você pode ter acesso aos encartes e aplicá-los manualmente. Em androidx.compose.material 1.6.0 Depois, use o parâmetro windowInsets para aplicar os encartes manualmente aos BottomAppBar, TopAppBar, BottomNavigation, e NavigationRail Da mesma forma, use o parâmetro contentWindowInsets para Scaffold. Você também pode aplicar os encartes manualmente como padding.

Inserção no processamento de elementos combináveis

Abaixo está uma lista de materiais componentes que para lidar automaticamente com encartes.

Barras de apps

• TopAppBar / SmallTopAppBar CenterAlignedTopAppBar / MediumTopAppBar / LargeTopAppBar: aplica as laterais superior e horizontal das barras do sistema como padding, já que elas são usadas 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 encartes vertical e início ao conteúdo.
• ModalBottomSheet: Aplica os encartes inferiores.
• NavigationBar: aplica os engastes inferior e horizontal.
• NavigationRail: aplica os encartes de vertical e início.

Scaffold

Por padrão, Scaffold fornece insets como parâmetro paddingValues para você consumir e usar. Scaffold não aplica os encartes ao conteúdo. essa responsabilidade é sua. Por exemplo, para consumir esses encartes 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

É possível mudar o parâmetro windowInsets transmitido ao elemento combinável para configurar o comportamento da função de composição. Esse parâmetro pode ser um tipo diferente de janela inserida para aplicar ou desativado ao transmitir uma instância vazia: WindowInsets(0, 0, 0, 0).

Por exemplo, para desativar o processamento do encarte 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

Talvez seja necessário substituir os insetos padrão quando a tela tiver visualizações e código do Compose na mesma hierarquia. Nesse caso, você precisa ser explícito em qual deles deve consumir os encartes 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, caso o layout mais externo seja um elemento combinável, consuma o elemento encartes no Compose e preencha os elementos combináveis AndroidView adequadamente.

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

Recursos

• 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 aplicação de ponta a ponta do 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: de ponta a ponta, volta preditiva e resumo: um vídeo do YouTube sobre a aplicação de ponta a ponta do Android 15
• De ponta a ponta e encartes | Dicas de escrita: um vídeo do YouTube que mostra como processar encartes para desenhar de ponta a ponta