Sobre os encartes de janela

A plataforma Android é responsável por desenhar a interface do sistema, como as barras de status e de navegação. Essa interface do sistema é mostrada 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 ocultada pela interface do sistema.

Figura 1. Usar o modo 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 de sistema e dos cortes da tela por padrão.

No Android 15 (nível 35 da API) e versões mais recentes, o app é renderizado abaixo das barras de sistema e dos cortes de tela 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 disponível na janela.

Mostrar conteúdo atrás da IU do sistema é chamado de exibição de ponta a ponta. Nesta página, você vai aprender sobre os diferentes tipos de encartes, como usar o recurso 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 exibição de ponta a ponta é obrigatória no Android 15 e versões mais recentes quando o app usa o SDK 35. Se o app ainda não estiver de ponta a ponta, algumas partes dele podem ficar ocultas, e você precisará processar as inserções. Dependendo do app, esse trabalho pode ou não ser significativo. O componente Scaffold do Material 3 pode reduzir o trabalho necessário para ser compatível com a aplicação de ponta a ponta do Android 15. Consulte Criar um componente de scaffold para manter a IU unida.

Fundamentos de inserção

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

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

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

Estes tipos de margem integrados do Android estão disponíveis em WindowInsets:

WindowInsets.statusBars	As inserções que descrevem as barras de status. São as barras superiores da interface do sistema que contêm ícones de notificação e outros indicadores.
WindowInsets.statusBarsIgnoringVisibility	As inserções da barra de status para quando elas estão visíveis. Se as barras de status estiverem ocultas (devido à entrada no modo imersivo de tela cheia), as inserções da barra de status principal estarão vazias, mas essas inserções não estarão vazias.
WindowInsets.navigationBars	As inserções que descrevem as barras de navegação. São as barras da interface do sistema à esquerda, à direita ou na parte de baixo do dispositivo, que descrevem a barra de tarefas ou os ícones de navegação. Elas podem mudar no momento da 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	As inserções da barra de navegação para quando elas estão visíveis. Se as barras de navegação estiverem ocultas (devido à entrada no modo imersivo de tela cheia), as inserções da barra de navegação principal estarão vazias, mas essas inserções não estarão vazias.
WindowInsets.captionBar	O encarte que descreve a decoração da janela da interface do sistema se estiver em uma janela com formato livre, como a barra de título da parte de cima.
WindowInsets.captionBarIgnoringVisibility	As inserções da barra de legenda para quando elas estão visíveis. Se as barras de legenda estiverem ocultas, as inserções da barra de legenda principal estarão vazias, mas essas inserções não estarão vazias.
WindowInsets.systemBars	A união das margens da barra de sistema, que inclui as barras de status, de navegação e de legenda.
WindowInsets.systemBarsIgnoringVisibility	As inserções da barra de sistema para quando elas estão visíveis. Se as barras de sistema estiverem ocultas (devido à entrada no modo imersivo de tela cheia), as inserções da barra de sistema principal estarão vazias, mas essas inserções não estarão vazias.
WindowInsets.ime	As inserções que descrevem a quantidade de espaço na parte de baixo que o teclado de software ocupa.
WindowInsets.imeAnimationSource	As inserções que descrevem a quantidade de espaço que o teclado de software ocupava antes da animação atual do teclado.
WindowInsets.imeAnimationTarget	As inserções que descrevem a quantidade de espaço que o teclado de software vai ocupar depois da animação atual.
WindowInsets.tappableElement	Um tipo de encarte que descreve informações mais detalhadas sobre a IU de navegação, fornecendo a quantidade de espaço em que os "toques" serão processados pelo sistema, e não pelo app. Para barras de navegação transparentes com navegação por gestos, alguns elementos do app podem ser tocados pela IU de navegação do sistema.
WindowInsets.tappableElementIgnoringVisibility	As inserções de elementos tocáveis para quando eles estão visíveis. Se os elementos tocáveis estiverem ocultos (devido à entrada no modo imersivo de tela cheia), as inserções do elemento tocável principal estarão vazias, mas essas inserções não estarão vazias.
WindowInsets.systemGestures	As inserções que representam a quantidade de inserções em que o sistema vai interceptar gestos para navegação. Os apps podem especificar manualmente o processamento de uma quantidade limitada desses gestos usando Modifier.systemGestureExclusion.
WindowInsets.mandatorySystemGestures	Um subconjunto dos gestos do sistema que sempre serão processados pelo sistema e que não podem ser desativados usando Modifier.systemGestureExclusion.
WindowInsets.displayCutout	As inserções que representam o espaçamento necessário para evitar a sobreposição com um corte da tela (notch ou pinhole).
WindowInsets.waterfall	As inserções que representam as áreas curvas de uma tela em cascata. Uma tela em cascata tem áreas curvas ao longo das bordas, onde a tela começa a se estender pelas laterais do dispositivo.

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

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

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

• Use WindowInsets.safeDrawing para proteger o conteúdo que não pode ser desenhado abaixo de qualquer interface do sistema. Esse é o uso mais comum de inserções: evitar que o conteúdo desenhado seja ocultado pela interface do sistema, seja parcial ou totalmente.
• Use WindowInsets.safeGestures para proteger o conteúdo com gestos. Isso evita que os gestos do sistema entrem em conflito com os 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.