Configura la visualizzazione edge-to-edge

La visualizzazione edge-to-edge consente all'app di disegnare la UI dietro le barre di sistema (barra di stato, barra del titolo e barra di navigazione) per un'esperienza utente più coinvolgente. Se scegli come target i dispositivi con Android 15 (livello API 35) o versioni successive, la modalità edge-to-edge viene applicata per impostazione predefinita.

Per visualizzare correttamente i contenuti edge-to-edge su tutte le versioni di Android, segui questi passaggi di configurazione. In caso contrario, l'app potrebbe disegnare colori a tinta unita dietro le barre di sistema o non animare i contenuti in modo sincrono con le transizioni della tastiera sullo schermo (IME).

1. Attiva la visualizzazione edge-to-edge

Per attivare la modalità edge-to-edge nelle versioni precedenti di Android, chiama enableEdgeToEdge() nel metodo Activity.onCreate():

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    ...
}

Per impostazione predefinita, enableEdgeToEdge() rende trasparenti le barre di sistema, tranne nella modalità di navigazione con tre pulsanti, in cui applica una schermata semitrasparente alla barra di navigazione per un contrasto migliore. Il colore delle icone di sistema e della schermata si adatta al tema chiaro o scuro del sistema.

2. Configura windowSoftInputMode

Imposta android:windowSoftInputMode="adjustResize" nella voce AndroidManifest.xml dell'attività. Questa impostazione consente all'app di ricevere gli inset IME, permettendoti di regolare il layout con la spaziatura interna quando la tastiera sullo schermo viene visualizzata o scompare.

<!-- In your AndroidManifest.xml file: -->
<activity
  android:name=".ui.MainActivity"
  android:label="@string/app_name"
  android:windowSoftInputMode="adjustResize"
  android:theme="@style/Theme.MyApplication"
  android:exported="true">
  ...
</activity>

3. Gestisci le sovrapposizioni utilizzando gli inset

Una volta attivata la modalità edge-to-edge, alcuni contenuti e alcuni elementi della UI dell'app potrebbero essere disegnati dietro le barre di sistema. Per evitare che gli elementi critici o interattivi vengano oscurati dalle barre di sistema o si sovrappongano ai gesti di sistema, devi gestire gli inset.

Gli inset descrivono le parti dello schermo che si intersecano con la UI di sistema o i gesti di sistema. I principali tipi di inset da considerare per la visualizzazione edge-to-edge sono:

• Inset delle barre di sistema: rappresentano le aree in cui vengono visualizzate le barre di sistema. Utilizzali per evitare che la UI venga oscurata dalle barre di sistema.
• Inset del ritaglio del display: rappresentano le aree in cui è presente un ritaglio fisico (ad esempio una tacca della fotocamera) sullo schermo del dispositivo.

In Compose, puoi gestire gli inset utilizzando righelli, modificatori di spaziatura interna o modificatori delle dimensioni degli inset. Per istruzioni dettagliate, consulta Informazioni sugli inset delle finestre.

Argomenti avanzati

Per casi d'uso edge-to-edge più avanzati, tieni presente quanto segue.

Modalità immersiva

Alcuni contenuti, come video o mappe, traggono vantaggio da un'esperienza completamente immersiva in cui le barre di sistema sono nascoste. Puoi nascondere le barre di sistema utilizzando WindowInsetsControllerCompat:

val windowInsetsController =
    WindowCompat.getInsetsController(window, window.decorView)

// Hide the system bars.
windowInsetsController.hide(WindowInsetsCompat.Type.systemBars())

// Show the system bars.
windowInsetsController.show(WindowInsetsCompat.Type.systemBars()) For example, use either `Scaffold`,

Colori e icone delle barre di sistema

Quando passi alla modalità edge-to-edge, lo sfondo dell'app potrebbe essere visibile dietro le barre di sistema, quindi potresti dover regolare i colori delle icone delle barre di sistema per un contrasto migliore.

Per modificare le icone della barra di stato in chiaro o scuro, utilizza WindowInsetsControllerCompat:

// Set status bar icons to dark
WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = true

// Set status bar icons to light
WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = false

Protezione delle barre di sistema

Sebbene enableEdgeToEdge() fornisca barre di sistema trasparenti o semitrasparenti predefinite, potresti doverle personalizzare. Consulta le linee guida di progettazione delle barre di sistema Android e le linee guida di progettazione edge-to-edge per decidere quando utilizzare barre trasparenti o semitrasparenti.

Per rendere completamente trasparente la navigazione con tre pulsanti anziché semitrasparente, puoi disattivare l'applicazione del contrasto:

window.isNavigationBarContrastEnforced = false

Per ulteriori informazioni, consulta Informazioni sulla protezione delle barre di sistema.

Finestre di dialogo

Per visualizzare le finestre di dialogo a schermo intero in modalità edge-to-edge, chiama WindowCompat.enableEdgeToEdge nel metodo onStart() della finestra di dialogo:

class MyAlertDialogFragment : DialogFragment() {
    override fun onStart(){
        super.onStart()
        dialog?.window?.let { WindowCompat.enableEdgeToEdge(it) }
    }
    ...
}