Aggiunta del supporto per il gesto Indietro predittivo

Indietro predittivo, una funzionalità di navigazione tramite gesti, consente agli utenti di visualizzare in anteprima la destinazione dello scorrimento indietro.

Ad esempio, l'utilizzo di un gesto Indietro può mostrare un'anteprima animata della schermata Home dietro l'app, come mostrato nel mockup della Figura 1.

A partire da Android 15, l'opzione sviluppatore per le animazioni Indietro predittivo non è più disponibile. Le animazioni di sistema, come il ritorno alla home page, il passaggio da un'attività all'altra e il passaggio da un'attività all'altra, ora vengono visualizzate per le app che hanno attivato il gesto Indietro predittivo interamente o a livello di attività.

Puoi testare questa animazione di ritorno alla home (come descritto in una sezione successiva di questa pagina).

Per supportare il gesto Indietro predittivo, devi aggiornare l'app utilizzando l'API OnBackPressedCallback compatibile con le versioni precedenti in AndroidX Activity 1.6.0 o versioni successive oppure la nuova API della piattaforma OnBackInvokedCallback. La maggior parte delle app utilizza l'API AndroidX compatibile con le versioni precedenti.

Questo aggiornamento fornisce un percorso di migrazione per intercettare correttamente la navigazione a ritroso, che prevede la sostituzione delle intercettazioni della navigazione a ritroso da KeyEvent.KEYCODE_BACK e di tutte le classi con metodi onBackPressed come Activity e Dialog con le nuove API di sistema per la navigazione a ritroso.

Codelab e video di Google I/O

Oltre a utilizzare la documentazione in questa pagina, prova il nostro codelab. Fornisce un'implementazione di un caso d'uso comune di una WebView che gestisce il gesto Indietro predittivo utilizzando le API AndroidX Activity.

Puoi anche guardare il nostro video di Google I/O, che illustra altri esempi di implementazione delle API AndroidX e della piattaforma.

Gestisci i gesti Indietro personalizzati in Compose

Compose fornisce il composable PredictiveBackHandler per gestire i gesti Indietro personalizzati. Questa API ti consente di rispondere al gesto Indietro e fornisce un Flow di oggetti BackEventCompat che puoi utilizzare per implementare animazioni o transizioni personalizzate mentre l'utente scorre.

Per utilizzare PredictiveBackHandler, assicurati che la tua app includa la dipendenza androidx.activity:activity-compose (versione 1.8.0 o successive):

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}

PredictiveBackHandler(enabled = isBackHandlerEnabled) { progress: Flow<BackEventCompat> ->
    try {
        progress.collect { backEvent ->
            // Update your UI or animation based on backEvent.progress.
        }
        // Handle the final back action (e.g., navigate back).
    } catch (e: CancellationException) {
        // Back gesture was cancelled, reset your UI.
    }
}
PredictiveBackSnippets.kt

Se devi solo intercettare il gesto Indietro senza monitorare l'avanzamento, utilizza BackHandler.

Aggiorna un'app che utilizza la navigazione a ritroso predefinita

La funzionalità Indietro predittivo è attiva per impostazione predefinita.

Se la tua app utilizza frammenti o il componente di navigazione, esegui l'upgrade anche ad AndroidX Activity 1.6.0 o versioni successive.

Aggiorna un'app che utilizza la navigazione a ritroso personalizzata

Se la tua app implementa un comportamento personalizzato per il pulsante Indietro, esistono diversi percorsi di migrazione a seconda che utilizzi AndroidX e di come gestisca la navigazione a ritroso.

Esegui la migrazione di un'implementazione della navigazione a ritroso di AndroidX

Questo caso d'uso è il più comune (e il più consigliato). Si applica alle app nuove o esistenti che implementano la gestione personalizzata della navigazione tramite gesti con OnBackPressedDispatcher, come descritto in Fornisci una navigazione a ritroso personalizzata.

Per assicurarti che le API che utilizzano già OnBackPressedDispatcher (come i frammenti e il componente di navigazione) funzionino perfettamente con il gesto Indietro predittivo, esegui l'upgrade ad AndroidX Activity 1.6.0 o versioni successive.

// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

Esegui la migrazione di un'app AndroidX contenente API di navigazione a ritroso non supportate alle API AndroidX

Se la tua app utilizza le librerie AndroidX, ma implementa o fa riferimento alle API di navigazione a ritroso non supportate, dovrai eseguire la migrazione all'utilizzo delle API AndroidX per supportare il nuovo comportamento.

Per eseguire la migrazione delle API non supportate alle API AndroidX:

1. Esegui la migrazione della logica di gestione del pulsante Indietro del sistema a OnBackPressedDispatcher di AndroidX con un'implementazione di OnBackPressedCallback. Per indicazioni dettagliate, consulta Fornisci una navigazione a ritroso personalizzata.

2. Disattiva OnBackPressedCallback quando vuoi interrompere l'intercettazione del gesto Indietro.

3. Interrompi l'intercettazione degli eventi Indietro utilizzando OnBackPressed o KeyEvent.KEYCODE_BACK.

4. Assicurati di eseguire l'upgrade ad AndroidX Activity 1.6.0 o versioni successive.

   // In your build.gradle file:
   dependencies {
       // Add this in addition to your other dependencies
       implementation "androidx.activity:activity:1.6.0"
   }
   

Disattiva il gesto Indietro predittivo

Per disattivare questa funzionalità, in AndroidManifest.xml, nel tag <application>, imposta il flag android:enableOnBackInvokedCallback su false.

<application
    ...
    android:enableOnBackInvokedCallback="false"
    ... >
...
</application>

Se viene impostato su false, si verifica quanto segue:

• Disattiva l'animazione di sistema per il gesto Indietro predittivo.
• Ignora OnBackInvokedCallback, ma le chiamate OnBackPressedCallback continuano a funzionare.

Disattivazione a livello di attività

Il flag android:enableOnBackInvokedCallback ti consente di disattivare le animazioni di sistema predittive a livello di attività. Questo comportamento semplifica la migrazione di app di grandi dimensioni con più attività ai gesti Indietro predittivi.

Il seguente codice mostra un esempio di enableOnBackInvokedCallback impostato per attivare l'animazione di sistema di ritorno alla home page da MainActivity:

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

        <activity
            android:name=".MainActivity"
            android:enableOnBackInvokedCallback="true"
            ...
        </activity>
        <activity
            android:name=".SecondActivity"
            android:enableOnBackInvokedCallback="false"
            ...
        </activity>
    </application>
</manifest>

Tieni presente quanto segue quando utilizzi il flag android:enableOnBackInvokedCallback:

• L'impostazione android:enableOnBackInvokedCallback=false disattiva le animazioni di Indietro predittivo a livello di attività o di app, a seconda di dove imposti il tag, e indica al sistema di ignorare le chiamate all'API della piattaforma OnBackInvokedCallback. Tuttavia, le chiamate a OnBackPressedCallback continuano a essere eseguite perché OnBackPressedCallback è compatibile con le versioni precedenti e chiama l'API onBackPressed, che non è supportata prima di Android 13.
• L'impostazione del flag enableOnBackInvokedCallback a livello di app stabilisce il valore predefinito per tutte le attività nell'app. Puoi eseguire l'override del valore predefinito per attività impostando il flag a livello di attività, come mostrato nell'esempio di codice precedente.

Linee guida per i callback

Segui queste linee guida quando utilizzi i callback di ritorno del sistema supportati: PredictiveBackHandler o BackHandler (per Compose), OnBackPressedCallback o OnBackInvokedCallback.

Determina lo stato della UI che attiva e disattiva ogni callback

Stato della UI è una proprietà che descrive la UI. Ti consigliamo di seguire questi passaggi generali.

1. Determina lo stato della UI che attiva e disattiva ogni callback.

2. Definisci questo stato utilizzando un tipo di contenitore di dati osservabili, come StateFlow o Compose State, e attiva o disattiva il callback quando lo stato cambia.

Se in precedenza la tua app associava la logica del pulsante Indietro a istruzioni condizionali, questo potrebbe significare che stai reagendo all'evento Indietro dopo che si è già verificato. Evita questo pattern con i callback più recenti. Se possibile, sposta il callback all'esterno dell'istruzione condizionale e associalo a un tipo di contenitore di dati osservabile.

Utilizza i callback di ritorno del sistema per la logica della UI

La logica dell'interfaccia utente determina come visualizzare l'interfaccia utente. Utilizza i callback di sistema per l'indietro per eseguire la logica della UI, ad esempio la visualizzazione di una finestra di dialogo o l'esecuzione di un'animazione.

Se la tua app attiva un OnBackPressedCallback o un OnBackInvokedCallback con PRIORITY_DEFAULT o PRIORITY_OVERLAY, le animazioni di Indietro predittivo non vengono eseguite e devi gestire l'evento Indietro. Non creare questi callback per eseguire la logica di business o per la registrazione.

Utilizza i seguenti approcci se la tua app deve eseguire la logica di business o registrare quando l'utente scorre indietro:

• In Compose: registra all'interno del callback onCleared() di un ViewModel associato alla destinazione di Compose. Questo è l'indicatore migliore per sapere quando una destinazione di Compose viene rimossa dal back stack e distrutta.
• Su Android 16 e versioni successive: utilizza OnBackInvokedCallback con PRIORITY_SYSTEM_NAVIGATION_OBSERVER. In questo modo viene creato un callback dell'osservatore che non consuma l'evento "Indietro". Ad esempio, puoi registrare questo callback quando l'utente scorre indietro dall'attività principale (uscendo dalla tua app) per registrare l'evento Indietro o eseguire la logica di business, consentendo comunque la riproduzione dell'animazione di ritorno alla schermata Home.
• Nelle app basate su View:registra i log all'interno dei callback del ciclo di vita o del back stack anziché utilizzare gli eventi Indietro:
  • Per le transizioni di attività, controlla se isFinishing è true entro Activity.onDestroy().
  • Per le transizioni dei frammenti, controlla se isRemoving è true nel ciclo di vita della visualizzazione del frammento onDestroy() o utilizza FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted/onBackStackChangeCommitted).

Crea callback con una singola responsabilità

Puoi aggiungere più callback al dispatcher. I callback vengono aggiunti a uno stack in cui l'ultimo callback abilitato aggiunto gestisce il gesto Indietro successivo con un callback per gesto Indietro.

È più facile gestire lo stato di attivazione di un callback se questo ha una singola responsabilità. Ad esempio:

La Figura 2 mostra come puoi avere più callback nello stack, ognuno responsabile di un'operazione. In Compose, i callback vengono valutati dal composable più interno a quello più esterno e un callback viene eseguito solo se i callback che lo precedono nello stack sono disattivati:

• La finestra di dialogo "Vuoi davvero…" PredictiveBackHandler viene attivato quando l'utente inserisce i dati in un modulo e disattivato negli altri casi. Quando è abilitata, intercetta il gesto Indietro per visualizzare una finestra di dialogo di conferma o un'animazione in-app personalizzata.
• Il BackHandler a livello di schermata viene eseguito se il callback precedente è disattivato. In questo esempio, è disabilitato.
• Il callback NavHost gestisce la navigazione a ritroso per rimuovere le destinazioni dal back stack se i callback personalizzati precedenti sono disattivati.
• Infine, il sistema gestisce il gesto Indietro se tutti i callback precedenti sono disattivati. Quando il back stack si trova nella destinazione principale, il sistema attiva animazioni a livello di sistema, come il ritorno alla home page, il passaggio da un'attività all'altra e il passaggio da un'attività all'altra.

Lo stesso comportamento dello stack si applica alle app basate su View: l'ultimo OnBackPressedCallback abilitato aggiunto ha la precedenza, con il fallback a FragmentManager e infine alla gestione del pulsante Indietro del sistema.

Testa l'animazione del gesto Indietro predittivo

A partire da Android 15, le animazioni di sistema come il ritorno alla home page, il passaggio da un'attività all'altra e il passaggio da un'attività all'altra sono attivate per impostazione predefinita per le app che supportano l'Indietro predittivo. Non sono più nascoste dietro un'opzione sviluppatore.

Sui dispositivi con Android 13 o Android 14, puoi attivare l'opzione sviluppatore per testare l'animazione di ritorno alla home mostrata nella Figura 1:

1. Sul dispositivo, vai a Impostazioni > Sistema > Opzioni sviluppatore.

2. Seleziona Animazioni Indietro predittivo.

3. Avvia l'app aggiornata e utilizza il gesto Indietro per vederlo in azione.