Mostrar conteúdo de ponta a ponta no app

Testar o Compose
O Jetpack Compose é o kit de ferramentas de interface recomendado para Android. Aprenda a trabalhar com ponta a ponta no Compose.
De ponta a ponta no Compose →

Depois de segmentar o SDK 35 ou mais recente em um dispositivo com o Android 15 ou mais recente, seu app é exibido de ponta a ponta. A janela abrange toda a largura e altura da tela, desenhando atrás das barras do sistema. As barras de sistema incluem o status de legenda e de navegação.

Muitos apps têm uma barra de apps na parte de cima. A barra de apps superior deve se esticar até a borda superior do da tela e serão exibidos 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 rolar.

Muitos apps também têm uma barra de apps ou uma barra de navegação na parte de baixo da tela. Essas barras devem também podem se estender até a borda inferior da tela e serem exibidas atrás da navegação barra. Caso contrário, os apps precisam mostrar conteúdo de rolagem atrás da barra de navegação.

Figura 1. Barras de sistema em um layout de ponta a ponta.

Ao implementar um layout de ponta a ponta no app, mantenha o seguinte em em mente:

  1. Ativar uma tela de ponta a ponta
  2. Gerencie as sobreposições visuais.
  3. Considere mostrar scrims atrás das barras do sistema.
.
um exemplo de imagem por trás da barra de status
Figura 2. Exemplo de imagem por trás na barra de status.
.

Ativar a exibição de ponta a ponta

Se o app for direcionado ao SDK 35 ou mais recente, a navegação de ponta a ponta será ativada automaticamente para Dispositivos Android 15 ou mais recente.

Para ativar a navegação de ponta a ponta em versões anteriores do Android, faça o seguinte:

  1. Adicione uma dependência à biblioteca Biblioteca androidx.activity na build.gradle do seu 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'
}

  2. Importe o arquivo enableEdgeToEdge no seu aplicativo:

Para ativar manualmente a exibição de ponta a ponta, chame enableEdgeToEdge. em onCreate dos seus 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 na Modo de navegação com três botões em que a barra de status tem um scrim translúcido. O as cores dos ícones do sistema e do scrim são ajustadas de acordo com o sistema claro ou escuro.

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 o enableEdgeToEdge(), consulte Configurar manualmente a tela 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 lidar com as sobreposições reagindo aos encartes, que especificam quais partes a tela cruzar com a IU do sistema, como a barra de navegação ou o status barra. A interseção pode significar a exibição acima do conteúdo, mas também pode informar seu app sobre gestos do sistema.

Os tipos de encarte que se aplicam à exibição do app de ponta a ponta são:

  • Encartes de barras de sistema:melhor para visualizações tocáveis e que não podem visualmente escondidas pelas barras do sistema.

  • Encartes de corte da tela:para áreas em que pode haver um corte de 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 seu app.

Encartes de barras do sistema

Os encartes da barra do sistema são o tipo mais usado. Eles representam área em que a interface do sistema é exibida no eixo Z acima do app. São melhores usadas para mover ou preencher visualizações no app que são tocáveis e que não podem ser visualmente obscurecidos pelas barras do sistema.

Por exemplo, a ação flutuante FAB (FAB) na Figura 3 está parcialmente ocultos pela barra de navegação:

um exemplo de implementação de ponta a ponta, mas a barra de navegação está cobrindo o FAB
Figura 3. Barra de navegação sobrepondo um FAB em uma layout de ponta a ponta.

Para evitar esse tipo de sobreposição visual no modo de gesto ou de botão, 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, o resultado não será sobreposição visual no modo de botão, conforme mostrado na figura 4:

uma barra de navegação translúcida não cobrindo o FAB
Figura 4. Resolvendo sobreposição visual no botão modo

O mesmo se aplica ao modo de navegação por gestos, como mostrado na Figura 5:

de ponta a ponta com a navegação por gestos
Figura 5. Resolvendo sobreposição visual no gesto modo de navegação.

Encartes de corte da tela

Alguns dispositivos têm cortes da tela. Normalmente, o corte fica na parte superior e incluída na barra de status. Quando a tela do dispositivo estiver no modo paisagem o corte pode estar na borda vertical. Dependendo do conteúdo que seu app é mostrado na tela, implemente padding para evitar cortes da tela, já que por padrão, os apps vão desenhar no corte da tela.

Por exemplo, muitas telas de apps mostram uma lista de itens. Não ocultar os itens da 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 tomando a lógica or da barras de sistema e tipos de corte da tela.

Defina clipToPadding como RecyclerView para que o padding role com a tecla itens de lista. Isso permite que os itens fiquem atrás das barras do sistema quando o usuário rolagens, como mostrado no exemplo a seguir.

<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 seu app. Essas áreas são mostradas em laranja na Figura 6:

Exemplo de encarte de gestos do sistema
Figura 6. Encartes de gestos do sistema.

Assim como os encartes da barra do sistema, você pode evitar sobrepor os encartes dos gestos do sistema. usando getInsets(int) com WindowInsetsCompat.Type.systemGestures()

Use esses encartes para mover ou preencher visualizações deslizantes para longe das bordas. Uso comum os casos incluem páginas inferiores, deslizar nos 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 inferior para o um gesto de tela inicial e um encarte esquerdo e direito para os gestos de voltar:

um exemplo de medições de encarte de gestos do sistema
Figura 7. Medições de encarte de gestos do sistema.

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

Vários componentes do Material Design do Android baseados em visualizações. (com.google.android.material){:.external} lida automaticamente com encartes, incluindo BottomAppBar, BottomNavigationView, NavigationRailView e NavigationView

No entanto, AppBarLayout não processa encartes automaticamente. Adicionar android:fitsSystemWindows="true" para processar os encartes superiores ou use setOnApplyWindowInsetsListener.

Saiba como lidar com encartes com Componentes do Material Design no Compose.

Modo imersivo

Alguns conteúdos têm melhor experiência em tela cheia, oferecendo ao usuário uma experiência mais imersiva. Você pode ocultar as barras de sistema e para o modo imersivo usando WindowInsetsController e WindowInsetsControllerCompat bibliotecas:

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 as 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 gesto WindowInsets navegação e como os encartes funcionam: