Aggiunta del supporto per il gesto Indietro predittivo

**Figura 1.** Mockup dell'aspetto e del comportamento del gesto Indietro predittivo su uno smartphone

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ò visualizzare un'anteprima animata della schermata Home dietro l'app, come mostrato nel mockup nella figura 1.

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

Puoi testare questa animazione Torna alla schermata Home (come descritto in una sezione successiva di questa pagina).

Per supportare il gesto Indietro predittivo, devi aggiornare l'app utilizzando l' API OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) o versioni successive compatibile con le versioni precedenti oppure utilizzando la nuova API della OnBackInvokedCallback piattaforma. 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 a ritroso da KeyEvent.KEYCODE_BACK e di qualsiasi classe con metodi onBackPressed, come Activity e Dialog, con le nuove API di sistema Indietro.

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 un WebView che gestisce il gesto Indietro predittivo utilizzando le API Activity di AndroidX.

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

Gestire i gesti Indietro personalizzati in Compose

Compose fornisce il componente componibile 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.

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
    }
}

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

Aggiornare un'app che utilizza la navigazione a ritroso predefinita

Indietro predittivo è attivato per impostazione predefinita.

Se la tua app utilizza Fragment o il componente di navigazione, esegui l'upgrade anche a AndroidX Activity 1.6.0-alpha05 o versioni successive.

Aggiornare un'app che utilizza la navigazione a ritroso personalizzata

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

Come la tua app gestisce la navigazione a ritroso	Percorso di migrazione consigliato (link in questa pagina)
API AndroidX	Eseguire la migrazione di un'implementazione Indietro AndroidX esistente
API della piattaforma non supportate	Eseguire la migrazione di un'app AndroidX contenente API di navigazione a ritroso non supportate alle API AndroidX

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

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

Per assicurarti che le API che utilizzano già OnBackPressedDispatcher (come Fragment e il componente di navigazione) funzionino senza problemi con il gesto Indietro predittivo, esegui l'upgrade a AndroidX Activity 1.6.0-alpha05.

```xml
// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```

Eseguire 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:

Esegui la migrazione della logica di gestione Indietro del sistema a AndroidX’s OnBackPressedDispatcher con un'implementazione di OnBackPressedCallback. Per indicazioni dettagliate, consulta Fornire una navigazione a ritroso personalizzata.
Disattiva OnBackPressedCallback quando è tutto pronto per interrompere l'intercettazione del gesto Indietro.
Interrompi l'intercettazione degli eventi Indietro tramite OnBackPressed o KeyEvent.KEYCODE_BACK.
Assicurati di eseguire l'upgrade ad AndroidX Activity 1.6.0-alpha05.
```
// In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"
```
Nota: OnBackPressedCallback viene sempre chiamato indipendentemente dal valore di android:enableOnBackInvokedCallback. In altre parole, la disattivazione dell'animazione di sistema non influisce sulla logica di gestione Indietro dell'app se utilizza OnBackPressedCallback.

Disattivare Indietro predittivo

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

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

Se imposti questo valore su false, si verifica quanto segue:

L'animazione di sistema del gesto Indietro predittivo viene disattivata.
OnBackInvokedCallback viene ignorato, ma le chiamate OnBackPressedCallback continuano a funzionare.

Disattivare 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 Torna alla schermata Home 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 le seguenti considerazioni quando utilizzi il flag android:enableOnBackInvokedCallback:

Se imposti android:enableOnBackInvokedCallback=false, le animazioni Indietro predittive vengono disattivate a livello di attività o di app, a seconda di dove imposti il tag, e il sistema viene istruito a 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.
Se imposti il flag enableOnBackInvokedCallback a livello di app, viene stabilito il valore predefinito per tutte le attività dell'app. Puoi sostituire il valore predefinito per attività impostando il flag a livello di attività, come mostrato nell'esempio di codice precedente.

Best practice per i callback

Ecco le best practice per l'utilizzo dei callback Indietro di sistema supportati: PredictiveBackHandler o BackHandler (per Compose), OnBackPressedCallback o OnBackInvokedCallback.

Determinare lo stato dell'UI che attiva e disattiva ogni callback

Lo stato dell'UI è una proprietà che descrive l'UI. Ti consigliamo di seguire questi passaggi di alto livello.

Determina lo stato dell'UI che attiva e disattiva ogni callback.
Definisci lo stato utilizzando un holder di dati osservabile tipo, come StateFlow o Compose State, e attiva o disattiva il callback quando lo stato cambia.

Se in precedenza la tua app associava la logica Indietro alle istruzioni condizionali, ciò 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 associa invece il callback a un tipo di holder di dati osservabile.

Utilizzare i callback Indietro di sistema per la logica dell'UI

La logica dell'UI determina come visualizzare l'UI. Utilizza i callback Indietro di sistema per eseguire la logica dell'UI, ad esempio visualizzare una finestra di dialogo o eseguire un'animazione.

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

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

Utilizza OnBackInvokedCallback con PRIORITY_SYSTEM_NAVIGATION_OBSERVER sui dispositivi con Android 16 e versioni successive. Viene creato un callback di osservatore che non utilizza l'evento Indietro. Ad esempio, puoi registrare questo callback quando l'utente scorre indietro dall'attività principale, in altre parole, quando l'utente ha lasciato l'app. In questo caso, puoi registrare l'evento Indietro o eseguire un'altra logica di business e l'animazione Torna alla schermata Home verrà comunque riprodotta.
Per i casi da attività ad attività o da fragment ad attività, registra se isFinishing in onDestroy è true nel ciclo di vita dell'attività.
Per i casi da fragment a fragment, registra se isRemoving in onDestroy è true nel ciclo di vita della visualizzazione del fragment. In alternativa, registra utilizzando i metodi onBackStackChangeStarted o onBackStackChangeCommitted in FragmentManager.OnBackStackChangedListener.
Per il caso di Compose, registra all'interno del callback onCleared() di un ViewModel associato alla destinazione Compose. Questo è il segnale migliore per sapere quando una destinazione Compose viene rimossa dal back stack e distrutta.

Creare callback a responsabilità singola

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 abilitato di un callback se questo ha una singola responsabilità. Ad esempio:

Ordine dei callback in uno stack. — **Figura 2.** Diagramma dello stack di callback.

La figura 2 mostra come puoi avere più callback nello stack, ognuno responsabile di una cosa. Un callback viene eseguito solo se i callback sopra di esso nello stack sono disattivati. In questo esempio, il callback "Vuoi uscire?" è attivato quando l'utente inserisce i dati in un modulo e disattivato in caso contrario. Il callback apre una finestra di dialogo di conferma quando l'utente scorre indietro per uscire dal modulo.

L'altro callback può includere un componente Material che supporta Indietro predittivo, una transizione AndroidX che utilizza le API Progress o un altro callback personalizzato.

Lo stesso comportamento dello stack si applica in Compose: PredictiveBackHandler o BackHandler più interno ha la precedenza.

Allo stesso modo, il callback di un childFragmentManager viene eseguito se i callback precedenti sono disattivati e il back stack per questo FragmentManager non è vuoto. In questo esempio, questo callback interno è disattivato.

Allo stesso modo, il callback interno di supportFragmentManager viene eseguito se i callback precedenti sono disattivati e il relativo stack non è vuoto. In questo esempio, questo callback viene eseguito se l'utente non ha inserito testo nel modulo, causando la disattivazione del callback "Vuoi uscire?".

Infine, il sistema gestisce il gesto Indietro se i callback precedenti sono disattivati. Per attivare le animazioni di sistema come Torna alla schermata Home, Passa da un'attività all'altra e Passa da un'app all'altra, il back stack di supportFragmentManager deve essere vuoto in modo che il callback interno sia disattivato.

Testare l'animazione del gesto Indietro predittivo

Se utilizzi ancora Android 13 o Android 14, puoi testare l'animazione Torna alla schermata Home mostrata nella figura 1.

Per testare questa animazione:

Sul dispositivo, vai a Impostazioni > Sistema > Opzioni sviluppatore.
Seleziona Animazioni Indietro predittivo.
Avvia l'app aggiornata e utilizza il gesto Indietro per vederla in azione.