Mostrare i contenuti a tutto schermo nelle visualizzazioni

Prova la funzionalità Scrivi
Jetpack Compose è il toolkit per l'interfaccia utente consigliato per Android. Scopri come utilizzare la funzionalità a tutto schermo in Scrivi.
Da bordo a bordo in Componi →

Una volta scelto come target l'SDK 35 o versioni successive su un dispositivo con Android 15 o versioni successive, la tua app viene visualizzata in modalità edge-to-edge. La finestra occupa l'intera larghezza e altezza del display disegnando dietro le barre di sistema. Le barre di sistema includono la barra di stato, la barra dei sottotitoli codificati e la barra di navigazione.

Molte app hanno una barra delle app nella parte superiore. La barra delle app superiore deve estendersi fino al bordo superiore dello schermo e essere visualizzata dietro la barra di stato. Se vuoi, la barra delle app superiore può essere ridotta all'altezza della barra di stato quando i contenuti scorrono.

Molte app hanno anche una barra delle app o una barra di navigazione in basso. Queste barre devono anche estendersi fino al bordo inferiore dello schermo e essere visualizzate dietro la barra di navigazione. In caso contrario, le app devono mostrare i contenuti in scorrimento dietro la barra di navigazione.

Figura 1. Barre di sistema in un layout edge-to-edge.

Quando implementi un layout da un'estremità all'altra nell'app, tieni presente quanto segue:

  1. Attivare un display edge-to-edge
  2. Gestisci eventuali sovrapposizioni visive.
  3. Valuta la possibilità di mostrare scrim dietro le barre di sistema.
un esempio di immagini dietro la barra di stato
Figura 2. Esempio di immagini dietro la barra di stato.

Attiva la visualizzazione edge-to-edge

Se la tua app ha come target l'SDK 35 o versioni successive, la modalità edge-to-edge viene attivata automaticamente per i dispositivi Android 15 o versioni successive.

Per attivare la visualizzazione a tutto schermo sulle versioni precedenti di Android:

  1. Aggiungi una dipendenza alla libreria androidx.activity nel build.gradle file della tua app o del tuo modulo:

    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. Importa la funzione di estensione enableEdgeToEdge nella tua app:

Attiva manualmente la visualizzazione edge-to-edge chiamando enableEdgeToEdge in onCreate del tuo Activity. Deve essere chiamato prima del giorno 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);
       ...
     }

Per impostazione predefinita, enableEdgeToEdge() rende trasparenti le barre di sistema, ad eccezione della modalità di navigazione con tre pulsanti, in cui la barra di stato viene visualizzata con una schermata semitrasparente. I colori delle icone di sistema e della maschera vengono regolati in base al tema chiaro o scuro del sistema.

La funzione enableEdgeToEdge() dichiara automaticamente che l'app deve essere disposta da un bordo all'altro e regola i colori delle barre di sistema.

Per attivare la visualizzazione edge-to-edge nella tua app senza utilizzare la funzioneenableEdgeToEdge(), consultaConfigurare manualmente la visualizzazione edge-to-edge.

Gestire le sovrapposizioni utilizzando gli inserti

Alcune visualizzazioni dell'app potrebbero essere disegnate dietro le barre di sistema, come mostrato nella figura 3.

Puoi risolvere le sovrapposizioni reagendo agli inserti, che specificano le parti dello schermo che si intersecano con l'interfaccia utente di sistema, come la barra di navigazione o la barra di stato. L'intersezione può significare la visualizzazione sopra i contenuti, ma può anche informare la tua app sui gesti di sistema.

I tipi di inserimenti che si applicano alla visualizzazione edge-to-edge dell'app sono:

  • Inserimento delle barre di sistema:ideale per le visualizzazioni che possono essere toccate e che non devono essere oscurate dalle barre di sistema.

  • Insegni ritaglio display:per le aree in cui potrebbe essere presente un ritaglio dello schermo a causa della forma del dispositivo.

  • Insegni dei gesti di sistema:per le aree di navigazione tramite gesti utilizzate dal sistema che hanno la priorità sulla tua app.

Inset delle barre di sistema

Gli inserti della barra di sistema sono il tipo di inserti più utilizzato. Rappresentano l'area in cui viene visualizzata l'interfaccia utente di sistema nell'asse Z sopra l'app. Sono ideali per spostare o aumentare le visualizzazioni nell'app che possono essere toccate e che non devono essere oscurate visivamente dalle barre di sistema.

Ad esempio, il pulsante di azione scorrevole (FAB) nella figura 3 è parzialmente oscurato dalla barra di navigazione:

un esempio di implementazione edge-to-edge, ma la barra di navigazione copre il pulsante flottante di accesso rapido
Figura 3. Barra di navigazione che si sovrappone a un pulsante di azione rapida in un layout da un'estremità all'altra.

Per evitare questo tipo di sovrapposizione visiva in modalità gesto o con i pulsanti, puoi aumentare i margini della visualizzazione utilizzando getInsets(int) con WindowInsetsCompat.Type.systemBars().

Il seguente esempio di codice mostra come implementare gli inserti della barra di 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 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 the window insets to keep passing
  // down to descendant views.
    return WindowInsetsCompat.CONSUMED;
});

Se applichi questa soluzione all'esempio mostrato nella figura 3, non si verifica alcuna sovrapposizione visiva in modalità pulsante, come mostrato nella figura 4:

una barra di navigazione traslucida che non copre il pulsante flottante.
Figura 4. Risoluzione della sovrapposizione visiva in modalità pulsante.

Lo stesso vale per la modalità di navigazione tramite gesti, come mostrato nella figura 5:

edge-to-edge con navigazione tramite gesti
Figura 5. Risoluzione della sovrapposizione visiva in modalità di navigazione tramite gesti.

Inset per il ritaglio del display

Alcuni dispositivi hanno ritagli sul display. In genere, il ritaglio si trova nella parte superiore dello schermo ed è incluso nella barra di stato. Quando lo schermo del dispositivo è in modalità Riquadro orizzontale, l'incisione potrebbe trovarsi sul bordo verticale. A seconda dei contenuti visualizzati dall'app sullo schermo, devi implementare i margini per evitare i ritagli del display, poiché per impostazione predefinita le app vengono disegnate nel ritaglio del display.

Ad esempio, molte schermate delle app mostrano un elenco di elementi. Non oscurare gli elementi dell'elenco con il ritaglio del display o le barre di 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) -> {
  Insets bars = insets.getInsets(
    WindowInsetsCompat.Type.systemBars()
    | WindowInsetsCompat.Type.displayCutout()
  );
  v.setPadding(bars.left, bars.top, bars.right, bars.bottom);
  return WindowInsetsCompat.CONSUMED;
});

Determina il valore di WindowInsetsCompat prendendo il valore logico OR delle barre di sistema e dei tipi di ritagli del display.

Imposta clipToPadding su RecyclerView in modo che il padding scorra con gli elementi dell'elenco. In questo modo, gli elementi vengono nascosti dietro le barre di sistema quando l'utente scorri, come mostrato nell'esempio seguente.

<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" />

Inset dei gesti di sistema

Gli inserti dei gesti di sistema rappresentano le aree della finestra in cui i gesti di sistema hanno la priorità sull'app. Queste aree sono mostrate in arancione nella figura 6:

Un esempio di rientranze dei gesti di sistema
Figura 6. Inset dei gesti di sistema.

Come per gli inserti della barra di sistema, puoi evitare di sovrapporre gli inserti dei gesti di sistema utilizzando getInsets(int) con WindowInsetsCompat.Type.systemGestures().

Utilizza questi rientri per spostare o aumentare le visualizzazioni scorrevoli dai bordi. I casi d'uso comuni includono sheet inferiori, scorrimento nei giochi e caroselli implementati utilizzando ViewPager2.

Su Android 10 o versioni successive, gli inset dei gesti di sistema contengono un inset in basso per il gesto di casa e un inset sinistro e destro per i gesti Indietro:

un esempio di misurazioni dell&#39;inset dei gesti di sistema
Figura 7. Misurazioni dell'inset dei gesti di sistema.

Il seguente esempio di codice mostra come implementare gli inserti dei gesti di 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;
});

Componenti Material

Molti Componenti Material di Android basati su visualizzazioni (com.google.android.material) gestiscono automaticamente gli inserti, tra cui BottomAppBar, BottomNavigationView, NavigationRailView e NavigationView

Tuttavia, AppBarLayout non gestisce automaticamente gli inserti. Aggiungi android:fitsSystemWindows="true" per gestire gli inserti superiori.

Scopri come gestire gli inserti con Componenti Material in Compose.

Invio di intestazioni compatibili con le versioni precedenti

Per interrompere l'invio di intestazioni alle visualizzazioni secondarie ed evitare un eccessivo spaziatura, puoi utilizzare la costante WindowInsetsCompat.CONSUMED. Tuttavia, sui dispositivi con Android 10 (livello API 29 e versioni precedenti), gli insiemi non vengono inviati ai fratelli dopo la chiamataWindowInsetsCompat.CONSUMED, il che può causare sovrapposizioni visive indesiderate.

Esempio di invio di intestazioni non valide
Figura 8. Esempio di invio di intestazioni non valide. Gli inset non vengono inviati alle visualizzazioni correlate dopo che ViewGroup 1 li ha consumati su Android 10 (livello API 29) e versioni precedenti, causando la sovrapposizione di TextView 2 con la barra di navigazione di sistema. Tuttavia, gli inset vengono inviati alle visualizzazioni con lo stesso layout su Android 11 (livello API 30) e versioni successive, come previsto.

Per confermare che gli insets vengono inviati ai componenti fratelli per tutte le versioni di Android supportate, utilizza ViewGroupCompat#installCompatInsetsDispatch prima di utilizzare gli insets, disponibili su AndroidX Core e Core-ktx 1.16.0-alpha01 e versioni successive.

Kotlin

// Use the i.d. assigned to your layout's root view, e.g. R.id.main
val rootView = findViewById(R.id.main)
// Call before consuming insets
ViewGroupCompat.installCompatInsetsDispatch(rootView)

Java

// Use the i.d. assigned to your layout's root view, e.g. R.id.main
LinearLayout rootView = findViewById(R.id.main);
// Call before consuming insets
ViewGroupCompat.installCompatInsetsDispatch(rootView);
Esempio di invio di intestazioni fisse
Figura 9. È stato corretto l'invio di inset dopo aver chiamato ViewGroupCompat#installCompatInsetsDispatch.

Modalità immersiva

Alcuni contenuti sono più adatti alla visualizzazione a schermo intero, offrendo all'utente un'esperienza più coinvolgente. Puoi nascondere le barre di sistema e la modalità immersiva utilizzando le librerie 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());

Per saperne di più sull'implementazione di questa funzionalità, consulta l'articolo Nascondere le barre di sistema per la modalità immersiva.

Icone della barra di sistema

La chiamata a enableEdgeToEdge garantisce l'aggiornamento dei colori delle icone della barra di sistema quando cambia il tema del dispositivo.

Quando passi allo schermo da un lato all'altro, potresti dover aggiornare manualmente i colori delle icone della barra di sistema in modo che contrastino con lo sfondo dell'app. Ad esempio, per creare icone della barra di stato chiare:

Kotlin

WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = false

Java

WindowCompat.getInsetsController(window, window.getDecorView())
    .setAppearanceLightStatusBars(false);

Protezione della barra di sistema

Una volta che l'app ha come target SDK 35 o versioni successive, viene applicato il rendering edge-to-edge. La barra di stato del sistema e le barre di navigazione tramite gesti sono trasparenti, ma la barra di navigazione con tre pulsanti è traslucida. Chiama enableEdgeToEdge per rendere compatibile con le versioni precedenti.

Tuttavia, i valori predefiniti del sistema potrebbero non funzionare per tutti i casi d'uso. Consulta le linee guida per la progettazione delle barre di sistema Android e il design edge-to-edge per determinare se utilizzare barre di sistema trasparenti o traslucide.

Creare barre di sistema trasparenti

Crea una barra di stato trasparente scegliendo come target Android 15 (SDK 35) o versioni successive o chiamando enableEdgeToEdge() con gli argomenti predefiniti per le versioni precedenti.

Crea una barra di navigazione con gesti trasparente scegliendo come target Android 15 o versioni successive o chiamando enableEdgeToEdge() con gli argomenti predefiniti per le versioni precedenti. Per la barra di navigazione con tre pulsanti, imposta Window.setNavigationBarContrastEnforced su false, altrimenti verrà applicato uno scrim traslucido.

Creare barre di sistema traslucide

Per creare una barra di stato traslucida:

  1. Aggiorna la dipendenza androidx-core alla versione 1.16.0-beta01 o successiva
  2. Inserisci il layout XML in androidx.core.view.insets.ProtectionLayout e assegna un ID.
  3. Accedi in modo programmatico a ProtectionLayout per impostare le protezioni, specificando il lato e un GradientProtection per la barra di stato.

<androidx.core.view.insets.ProtectionLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/list_protection"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <ScrollView
        android:id="@+id/item_list"
        android:clipToPadding="false"
        android:layout_width="match_parent"
        android:layout_height="match_parent">

        <!--items-->

    </ScrollView>

</androidx.core.view.insets.ProtectionLayout>
system_bar_protection.xml

val red = 52
val green = 168
val blue = 83
findViewById<ProtectionLayout>(R.id.list_protection)
    .setProtections(
        listOf(
            GradientProtection(
                WindowInsetsCompat.Side.TOP,
                // Ideally, this is the pane's background color
                // alpha = 204 for an 80% gradient
                Color.argb(204, red, green, blue)
            )
        )
    )
SystemBarProtectionSnippet.kt

Assicurati che il valore ColorInt passato a GradientProtection corrisponda allo sfondo del contenuto. Ad esempio, un layout di elenco dettagliato visualizzato su un dispositivo pieghevole potrebbe avere GradientProtections diversi di colori diversi per il riquadro dell'elenco e il riquadro dei dettagli.

Figura 1. Protezione con sfumatura di diversi colori.

Non creare una barra di navigazione con gesti traslucida. Per creare una barra di navigazione traslucida con tre pulsanti:

  • Se il layout è già racchiuso in un ProtectionView, puoi passare un altro ColorProtection o GradientProtection al metodo setProtections. Prima di procedere, assicurati che window.isNavigationBarContrastEnforced = false.
  • In caso contrario, imposta window.isNavigationBarContrastEnforced = true. Se le chiamate della tua app sono enableEdgeToEdge, window.isNavigationBarContrastEnforced = true, è il valore predefinito.

Altri suggerimenti

Verifica che l'ultimo elemento dell'elenco non sia oscurato dalle barre di sistema in RecyclerView o NestedScrollView gestendo gli inserti e impostando clipToPadding su false.

Il seguente video mostra un RecyclerView con il display edge-to-edge disattivato (a sinistra) e attivato (a destra):

Per un esempio di codice, consulta gli snippet di codice nella sezione Creare elenchi dinamici con RecyclerView.

Risorse aggiuntive

Per ulteriori informazioni sul passaggio a un layout a tutto schermo, consulta i seguenti riferimenti.

Blog

Design

Altra documentazione

Video