Depois de direcionar ao SDK 35 ou mais recente em um dispositivo com o Android 15 ou mais recente, o app é exibido de ponta a ponta. A janela abrange toda a largura e altura da tela, desenhando atrás das barras de sistema. As barras de sistema incluem a barra de status, a barra de legendas e a barra de navegação.
Muitos apps têm uma barra de apps na parte de cima. A barra de apps superior precisa se estender até a borda de cima da tela e ser mostrada atrás da barra de status. Opcionalmente, a barra de apps superior pode diminuir até a altura da barra de status quando o conteúdo é rolado.
Muitos apps também têm uma barra de apps ou uma barra de navegação na parte de baixo da tela. Essas barras também precisam se estender até a borda de baixo da tela e ser mostradas atrás da barra de navegação. Caso contrário, os apps precisam mostrar conteúdo de rolagem atrás da barra de navegação.
Ao implementar um layout de ponta a ponta no app, lembre-se do seguinte:
- Ativar uma tela de ponta a ponta
- Gerencie as sobreposições visuais.
- Considere mostrar scrims atrás das barras do sistema.
Ativar a exibição de ponta a ponta
Se o app for destinado ao SDK 35 ou mais recente, a navegação de ponta a ponta será ativada automaticamente para dispositivos com o Android 15 ou mais recente.
Para ativar a navegação de ponta a ponta em versões anteriores do Android, faça o seguinte:
Adicione uma dependência à biblioteca
androidx.activity
no arquivobuild.gradle
do app ou módulo:Kotlin
dependencies { val activity_version =
activity_version
// Java language implementation implementation("androidx.activity:activity:$activity_version") // Kotlin implementation("androidx.activity:activity-ktx:$activity_version") }Groovy
dependencies { def activity_version =
activity_version
// Java language implementation implementation 'androidx.activity:activity:$activity_version' // Kotlin implementation 'androidx.activity:activity-ktx:$activity_version' }Importe a função de extensão
enableEdgeToEdge
para seu app:
Ative manualmente a exibição de ponta a ponta chamando enableEdgeToEdge
em onCreate
do seu Activity
. Ele precisa ser chamado antes de setContentView
.
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { enableEdgeToEdge() super.onCreate(savedInstanceState) ... }
Java
@Override protected void onCreate(@Nullable Bundle savedInstanceState) { EdgeToEdge.enable(this); super.onCreate(savedInstanceState); ... }
Por padrão, enableEdgeToEdge()
torna as barras do sistema transparentes, exceto no
modo de navegação com três botões, em que a barra de status tem um scrim translúcido. As
cores dos ícones do sistema e do scrim são ajustadas com base no tema
claro ou escuro do sistema.
A função enableEdgeToEdge()
declara automaticamente que o app precisa ser
disposto de ponta a ponta e ajusta as cores das barras do sistema.
Para ativar a exibição de ponta a ponta no app sem usar a função
enableEdgeToEdge()
, consulte
Configurar manualmente a exibição de ponta a ponta.
Processar sobreposições usando encartes
Algumas das visualizações do seu app podem ficar atrás das barras de sistema, como mostrado na Figura 3.
Você pode resolver as sobreposições reagindo aos encartes, que especificam quais partes da tela se cruzam com a IU do sistema, como a barra de navegação ou a barra de status. A interseção pode significar a exibição acima do conteúdo, mas também pode informar ao app sobre gestos do sistema.
Os tipos de encarte que se aplicam à exibição do app de ponta a ponta são:
Encartes das barras de sistema:melhor para visualizações que podem ser tocadas e que não podem ser visualmente obscurecidas pelas barras de sistema.
Encartes de corte da tela:para áreas em que pode haver um corte da tela devido ao formato do dispositivo.
Encartes de gestos do sistema:para áreas de navegação por gestos usadas pelo sistema que têm prioridade sobre o app.
Encartes de barras do sistema
Os encartes da barra do sistema são o tipo mais usado. Eles representam a área em que a interface do sistema é mostrada no eixo Z acima do app. Eles são mais usados para mover ou preencher visualizações no app que podem ser tocadas e que não podem ser visualmente obscurecidas pelas barras do sistema.
Por exemplo, o botão de ação flutuante (FAB, na sigla em inglês) na Figura 3 é parcialmente oculto pela barra de navegação:
Para evitar esse tipo de sobreposição visual no modo de gesto ou de botão, você
pode aumentar as margens da visualização usando
getInsets(int)
com
WindowInsetsCompat.Type.systemBars()
.
O exemplo de código a seguir mostra como implementar encartes de barra do sistema:
Kotlin
ViewCompat.setOnApplyWindowInsetsListener(fab) { v, windowInsets -> val insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemBars()) // Apply the insets as a margin to the view. This solution sets // only the bottom, left, and right dimensions, but you can apply whichever // insets are appropriate to your layout. You can also update the view padding // if that's more appropriate. v.updateLayoutParams<MarginLayoutParams> { leftMargin = insets.left, bottomMargin = insets.bottom, rightMargin = insets.right, } // Return CONSUMED if you don't want want the window insets to keep passing // down to descendant views. WindowInsetsCompat.CONSUMED }
Java
ViewCompat.setOnApplyWindowInsetsListener(fab, (v, windowInsets) -> { Insets insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemBars()); // Apply the insets as a margin to the view. This solution sets only the // bottom, left, and right dimensions, but you can apply whichever insets are // appropriate to your layout. You can also update the view padding if that's // more appropriate. MarginLayoutParams mlp = (MarginLayoutParams) v.getLayoutParams(); mlp.leftMargin = insets.left; mlp.bottomMargin = insets.bottom; mlp.rightMargin = insets.right; v.setLayoutParams(mlp); // Return CONSUMED if you don't want want the window insets to keep passing // down to descendant views. return WindowInsetsCompat.CONSUMED; });
Se você aplicar essa solução ao exemplo mostrado na Figura 3, não haverá sobreposição visual no modo de botão, como mostrado na Figura 4:
O mesmo se aplica ao modo de navegação por gestos, como mostrado na Figura 5:
Encartes de corte da tela
Alguns dispositivos têm cortes da tela. Normalmente, ele fica na parte de cima da tela e é incluído na barra de status. Quando a tela do dispositivo está no modo paisagem, o corte pode estar na borda vertical. Dependendo do conteúdo que o app mostra na tela, implemente o padding para evitar cortes da tela, já que por padrão, os apps vão ser desenhados no corte da tela.
Por exemplo, muitas telas de apps mostram uma lista de itens. Não oculte itens de lista com o corte da tela ou as barras de sistema.
Kotlin
ViewCompat.setOnApplyWindowInsetsListener(binding.recyclerView) { v, insets -> val bars = insets.getInsets( WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout() ) v.updatePadding( left = bars.left, top = bars.top, right = bars.right, bottom = bars.bottom, ) WindowInsetsCompat.CONSUMED }
Java
ViewCompat.setOnApplyWindowInsetsListener(mBinding.recyclerView, (v, insets) -> { WindowInsetsCompat bars = insets.getInsets( WindowInsetsCompat.Type.systemBars() | WindowInsetsCompat.Type.displayCutout() ); v.setPadding(bars.left, bars.top, bars.right, bars.bottom); return WindowInsetsCompat.CONSUMED; });
Determine o valor de WindowInsetsCompat
usando o or lógico das
barras do sistema e dos tipos de corte da tela.
Defina clipToPadding
como RecyclerView
para que o padding role com os
itens da lista. Isso permite que os itens fiquem atrás das barras do sistema quando o usuário
rola a tela, conforme mostrado no exemplo abaixo.
<androidx.recyclerview.widget.RecyclerView
android:id="@+id/recycler_view"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:clipToPadding="false"
app:layoutManager="androidx.recyclerview.widget.LinearLayoutManager" />
Encartes de gestos do sistema
Os encartes de gestos do sistema representam as áreas da janela em que os gestos do sistema têm prioridade sobre o app. Essas áreas são mostradas em laranja na Figura 6:
Assim como os encartes da barra do sistema, você pode evitar a sobreposição dos encartes do gesto do sistema
usando
getInsets(int)
com
WindowInsetsCompat.Type.systemGestures()
.
Use esses encartes para mover ou preencher visualizações deslizantes para longe das bordas. Casos de uso
comuns incluem páginas inferiores,
deslizar em jogos e carrosséis implementados usando
ViewPager2
.
No Android 10 ou versões mais recentes, os encartes de gestos do sistema contêm um encarte de baixo para o gesto de início e um encarte à esquerda e à direita para os gestos "Voltar":
O exemplo de código abaixo mostra como implementar encartes de gestos do sistema:
Kotlin
ViewCompat.setOnApplyWindowInsetsListener(view) { view, windowInsets -> val insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemGestures()) // Apply the insets as padding to the view. Here, set all the dimensions // as appropriate to your layout. You can also update the view's margin if // more appropriate. view.updatePadding(insets.left, insets.top, insets.right, insets.bottom) // Return CONSUMED if you don't want the window insets to keep passing down // to descendant views. WindowInsetsCompat.CONSUMED }
Java
ViewCompat.setOnApplyWindowInsetsListener(view, (v, windowInsets) -> { Insets insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemGestures()); // Apply the insets as padding to the view. Here, set all the dimensions // as appropriate to your layout. You can also update the view's margin if // more appropriate. view.setPadding(insets.left, insets.top, insets.right, insets.bottom); // Return CONSUMED if you don't want the window insets to keep passing down // to descendant views. return WindowInsetsCompat.CONSUMED; });
Componentes do Material
Muitos componentes do Material Design do Android
(com.google.android.material){:.external} baseados em visualizações
processam automaticamente encartes, incluindo
BottomAppBar
,
BottomNavigationView
,
NavigationRailView
e NavigationView
No entanto, AppBarLayout
não processa automaticamente encartes. Adicione
android:fitsSystemWindows="true"
para processar os encartes superiores ou use setOnApplyWindowInsetsListener
.
Leia como processar encartes com Componentes do Material Design no Compose.
Modo imersivo
Alguns conteúdos são melhores em tela cheia, oferecendo ao usuário uma
experiência mais imersiva. Você pode ocultar as barras de sistema para o modo imersivo usando
as bibliotecas
WindowInsetsController
e
WindowInsetsControllerCompat
:
Kotlin
val windowInsetsController = WindowCompat.getInsetsController(window, window.decorView) // Hide the system bars. windowInsetsController.hide(Type.systemBars()) // Show the system bars. windowInsetsController.show(Type.systemBars())
Java
Window window = getWindow(); WindowInsetsControllerCompat windowInsetsController = WindowCompat.getInsetsController(window, window.getDecorView()); if (windowInsetsController == null) { return; } // Hide the system bars. windowInsetsController.hide(WindowInsetsCompat.Type.systemBars()); // Show the system bars. windowInsetsController.show(WindowInsetsCompat.Type.systemBars());
Consulte Ocultar barras de sistema para o modo imersivo para mais informações sobre como implementar esse recurso.
Outros recursos
Consulte as referências abaixo para saber mais sobre o WindowInsets
, a navegação
por gestos e como os encartes funcionam:
- WindowInsets: listeners para layouts
- Navegação por gestos: encartes
- Como os encartes funcionam no Android?