Sobre os encartes de janela

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 é mostrada independente do app que o usuário está usando.

O 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.

Renderização de ponta a ponta para mostrar atrás das barras de sistema
Figura 1. De ponta a ponta para renderizar atrás das barras de 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 da tela quando ele é 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.

Mostrar conteúdo atrás da interface do sistema é chamado de exibição de ponta a ponta. Nesta página, você vai aprender sobre os diferentes tipos de encartes, como ir 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 obscurecido por elementos da interface do sistema.

Fundamentos de encartes

Quando um app vai de ponta a ponta, é necessário garantir que o conteúdo e as interações importantes não sejam ocultados 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 está localizada são especificados via encartes.

Cada parte da interface do sistema tem um tipo correspondente de encarte que descreve o tamanho e a posição. Por exemplo, os encartes da barra de status fornecem o tamanho e a posição dela, enquanto os encartes 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 interface do sistema se estende das laterais correspondentes da janela do app. Para evitar a sobreposição com esse tipo de interface do sistema, a interface do app precisa ser inserida por essa quantidade.

Esses tipos de encartes integrados do Android estão disponíveis em WindowInsets:

WindowInsets.statusBars

Os encartes que descrevem as barras de status. São as principais barras de interface do usuário do sistema que contêm ícones de notificação e outros indicadores.

WindowInsets.statusBarsIgnoringVisibility

Os encartes da barra de status quando eles estão visíveis. Se as barras de status estiverem ocultas (devido à entrada no modo de tela cheia imersiva), as inclusões da barra de status principal estarão vazias, mas as inclusões de janela estarão preenchidas.

WindowInsets.navigationBars

Os encartes que descrevem as barras de navegação. São as barras da interface do sistema na lateral esquerda, direita ou na parte de baixo do dispositivo, que descrevem a barra de tarefas ou os ícones de navegação. Eles podem mudar no tempo de 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 barras de navegação são inseridas quando estão visíveis. Se as barras de navegação estiverem ocultas (devido à entrada no modo imersivo de tela cheia), os encartes da barra de navegação principal estarão vazios, mas esses encartes não estarão vazios.

WindowInsets.captionBar

O encarte que descreve a decoração da janela da interface do sistema em uma janela de formato livre, como a barra de título da parte de cima.

WindowInsets.captionBarIgnoringVisibility

As inclusões da barra de legenda quando elas estão visíveis. Se as barras de legenda estiverem ocultas, os encartes da barra de legenda principal vão estar vazios, mas esses encartes não estarão vazios.

WindowInsets.systemBars

A união dos encartes da barra de sistema, que incluem as barras de status, de navegação e de legenda.

WindowInsets.systemBarsIgnoringVisibility

Os encartes da barra de sistema quando eles estão visíveis. Se as barras de sistema estiverem ocultas (devido à entrada no modo de tela cheia imersiva), as inclusões da barra de sistema principal estarão vazias, mas essas inclusões não estarão vazias.

WindowInsets.ime

Os encartes que descrevem a quantidade de espaço na parte de baixo que o teclado de software ocupa.

WindowInsets.imeAnimationSource

Os encartes que descrevem a quantidade de espaço que o teclado virtual ocupou 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 atual do teclado.

WindowInsets.tappableElement

Um tipo de encartes que descreve informações mais detalhadas sobre a interface de navegação, informando 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 tocáveis na interface de navegação do sistema.

WindowInsets.tappableElementIgnoringVisibility

Os encartes 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), os encartes do elemento tocável principal vão estar vazios, mas esses encartes não estarão vazios.

WindowInsets.systemGestures

Os encartes que representam a quantidade de encartes 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 não podem ser desativados usando Modifier.systemGestureExclusion.

WindowInsets.displayCutout

Os encartes que representam a quantidade de espaçamento necessária para evitar a sobreposição com um corte da tela (entalhe ou furo).

WindowInsets.waterfall

Os encartes que representam as áreas curvas de uma exibição em cascata. Uma tela em cascata tem áreas curvas ao longo das bordas, onde ela começa a envolver as laterais do dispositivo.

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

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

  • Use WindowInsets.safeDrawing para proteger conteúdo que não deve ser desenhado abaixo de nenhuma interface do sistema. Esse é o uso mais comum de encartes: evitar desenhar conteúdo que está obscurecido pela interface do sistema (parcial ou totalmente).
  • Use WindowInsets.safeGestures para proteger o conteúdo com gestos. Isso evita que gestos do sistema entrem em conflito com gestos do app, como os de folhas 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.