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ò 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 di indietro predittive non è più disponibile. Le animazioni di sistema come il ritorno alla schermata Home, 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 page (come descritto in una sezione successiva di questa pagina).

Il supporto del gesto Indietro predittivo richiede l'aggiornamento dell'app, l'utilizzo dell'API compatibile con le versioni precedenti OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) o versioni successive oppure l'utilizzo della 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 indietro, che prevede la sostituzione delle intercettazioni del pulsante Indietro da KeyEvent.KEYCODE_BACK e di qualsiasi classe con metodi onBackPressed come Activity e Dialog con le nuove API Back di sistema.

Codelab e video di Google I/O

Oltre a utilizzare questa 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 Activity di AndroidX.

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

Aggiornare un'app che utilizza la navigazione indietro predefinita

La navigazione predittiva è attiva per impostazione predefinita.

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

Aggiornare un'app che utilizza la navigazione indietro personalizzata

Se la tua app implementa un comportamento di ritorno personalizzato, esistono diversi percorsi di migrazione a seconda che utilizzi AndroidX e di come gestisce la navigazione indietro.

Eseguire 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 della navigazione tramite gesti personalizzata con OnBackPressedDispatcher, come descritto in Fornire una navigazione indietro personalizzata.

Per assicurarti che le API che utilizzano già OnBackPressedDispatcher (come Fragment e il componente di navigazione) funzionino perfettamente con il gesto di indietro predittivo, esegui l'upgrade ad 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"
```

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

Se la tua app utilizza le librerie AndroidX, ma implementa o fa riferimento alle API di navigazione indietro 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 ad AndroidX OnBackPressedDispatcher con un'implementazione di OnBackPressedCallback. Per indicazioni dettagliate, vedi Fornire la navigazione indietro personalizzata.

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

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

4. 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"
   

Esegui la migrazione di un'app che utilizza API di navigazione indietro non supportate alle API della piattaforma

Se la tua app non può utilizzare le librerie AndroidX e implementa o fa riferimento alla navigazione Indietro personalizzata utilizzando le API non supportate, devi eseguire la migrazione all'OnBackInvokedCallbackAPI della piattaforma.

Completa i seguenti passaggi per eseguire la migrazione delle API non supportate all'API della piattaforma:

1. Utilizza la nuova API OnBackInvokedCallback sui dispositivi con Android 13 o versioni successive e fai affidamento sulle API non supportate sui dispositivi con Android 12 o versioni precedenti.

2. Registra la logica di navigazione indietro personalizzata in OnBackInvokedCallback con onBackInvokedDispatcher. In questo modo, l'attività corrente non viene terminata e il callback ha la possibilità di reagire all'azione Indietro una volta che l'utente completa la navigazione Indietro del sistema.

3. Annulla la registrazione di OnBackInvokedCallback quando è tutto pronto per interrompere l'intercettazione del gesto Indietro. In caso contrario, gli utenti potrebbero riscontrare un comportamento indesiderato quando utilizzano la navigazione Indietro del sistema, ad esempio "bloccarsi" tra le visualizzazioni e dover forzare l'uscita dall'app.

   Ecco un esempio di come eseguire la migrazione della logica da onBackPressed:

   Kotlin

   @Override
   fun onCreate() {
       if (BuildCompat.isAtLeastT()) {
           onBackInvokedDispatcher.registerOnBackInvokedCallback(
               OnBackInvokedDispatcher.PRIORITY_DEFAULT
           ) {
               /**
                * onBackPressed logic goes here. For instance:
                * Prevents closing the app to go home screen when in the
                * middle of entering data to a form
                * or from accidentally leaving a fragment with a WebView in it
                *
                * Unregistering the callback to stop intercepting the back gesture:
                * When the user transitions to the topmost screen (activity, fragment)
                * in the BackStack, unregister the callback by using
                * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
                * (https://developer.android.com/reference/kotlin/android/window/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
                */
           }
       }
   }

   Java

   @Override
   void onCreate() {
     if (BuildCompat.isAtLeastT()) {
       getOnBackInvokedDispatcher().registerOnBackInvokedCallback(
           OnBackInvokedDispatcher.PRIORITY_DEFAULT,
           () -> {
             /**
              * onBackPressed logic goes here - For instance:
              * Prevents closing the app to go home screen when in the
              * middle of entering data to a form
              * or from accidentally leaving a fragment with a WebView in it
              *
              * Unregistering the callback to stop intercepting the back gesture:
              * When the user transitions to the topmost screen (activity, fragment)
              * in the BackStack, unregister the callback by using
              * OnBackInvokeDispatcher.unregisterOnBackInvokedCallback
              * (https://developer.android.com/reference/kotlin/android/view/OnBackInvokedDispatcher#unregisteronbackinvokedcallback)
              */
           }
       );
     }
   }

4. Interrompi l'intercettazione degli eventi Indietro utilizzando OnBackPressed o KeyEvent.KEYCODE_BACK per Android 13 e versioni successive.

Puoi registrare un OnBackInvokedCallback con PRIORITY_DEFAULT o PRIORITY_OVERLAY, che non è disponibile nell'AndroidX simile OnBackPressedCallback. La registrazione di un callback con PRIORITY_OVERLAY è utile in alcuni casi.

Ciò si applica quando esegui la migrazione da onKeyPreIme() e il callback deve ricevere il gesto Indietro anziché una IME aperta. I metodi di input registrano i callback con PRIORITY_DEFAULT all'apertura. Registra il tuo callback con PRIORITY_OVERLAY per assicurarti che OnBackInvokedDispatcher invii il gesto Indietro al tuo callback anziché aprire l'IME.

Disattivare Indietro predittivo

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

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

Se imposti questo valore su false:

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

Disattivazione a livello di attività

A partire da Android 16, il flag android:enableOnBackInvokedCallback ti consente di disattivare le animazioni predittive del sistema 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 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 le seguenti considerazioni quando utilizzi il flag android:enableOnBackInvokedCallback:

• L'impostazione android:enableOnBackInvokedCallback=false disattiva le animazioni di ritorno 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 ignorare 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 del sistema supportati: BackHandler (per Compose), OnBackPressedCallback o OnBackInvokedCallback.

Determina lo stato dell'interfaccia utente che attiva e disattiva ogni callback

Stato dell'interfaccia utente è una proprietà che descrive l'interfaccia utente. Ti consigliamo di seguire questi passaggi di alto livello.

1. Determina lo stato dell'interfaccia utente che attiva e disattiva ogni callback.

2. Definisci questo stato utilizzando un tipo di contenitore di dati osservabile, ad esempio StateFlow o Compose State, e attiva o disattiva il callback al variare dello stato.

Se in precedenza la tua app associava la logica di ritorno a 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 al di fuori dell'istruzione condizionale e associa il callback a un tipo di contenitore di dati osservabile.

Utilizzare i callback di sistema per la logica dell'interfaccia utente

La logica dell'interfaccia utente determina come visualizzare l'interfaccia utente. Utilizza i callback di indietro del sistema per eseguire la logica dell'interfaccia utente, 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 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:

• Utilizza OnBackInvokedCallback con PRIORITY_SYSTEM_NAVIGATION_OBSERVER su dispositivi con Android 16 e versioni successive. Viene creata una richiamata dell'observer che non utilizza l'evento Indietro. Ad esempio, puoi registrare questo callback quando l'utente scorre indietro dall'attività principale o, in altre parole, quando ha lasciato la tua app. In questo caso, puoi registrare l'evento Indietro o eseguire altre logiche di business e l'animazione di ritorno alla home page verrà comunque riprodotta.
• Per i casi da attività ad attività o da frammento ad attività, registra se isFinishing all'interno di onDestroy è true all'interno del ciclo di vita dell'attività.
• Per i casi da frammento a frammento, registra se isRemoving all'interno di onDestroy è true all'interno del ciclo di vita della visualizzazione del frammento. In alternativa, accedi utilizzando i metodi onBackStackChangeStarted o onBackStackChangeCommitted all'interno di FragmentManager.OnBackStackChangedListener.
• Per lo scenario di composizione, registra il log all'interno del callback onCleared() di un ViewModel associato alla destinazione di composizione. Questo è il segnale migliore per sapere quando una destinazione di composizione viene rimossa dallo stack precedente e distrutta.

Crea 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 successivo gesto Indietro con un callback per gesto Indietro.

È più facile gestire lo stato abilitato 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 una cosa. Un callback viene eseguito solo se i callback precedenti nello stack sono disattivati. In questo esempio, il callback "Confermi..." è abilitato quando l'utente inserisce dati in un modulo e disabilitato in caso contrario. Il callback apre una finestra di dialogo di conferma quando l'utente scorre indietro per uscire dal modulo.

L'altra callback può includere un componente Material che supporta la navigazione predittiva, una transizione AndroidX che utilizza le API Progress o un'altra callback personalizzata.

Il callback di un childFragmentManager viene eseguito se i callback precedenti sono disattivati e lo stack precedente per questo FragmentManager non è vuoto, dove childFragmentManager è collegato a un fragment. 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. Questo comportamento è coerente quando si utilizza FragmentManager o NavigationComponent per la navigazione, poiché NavigationComponent si basa su FragmentManager. In questo esempio, questo callback viene eseguito se l'utente non ha inserito testo nel modulo, causando la disattivazione del callback "Vuoi continuare?".

Infine, super.onBackPressed()è il callback a livello di sistema, che viene eseguito se i callback precedenti sono disattivati. Per attivare le animazioni di sistema come Indietro alla home page, tra attività e tra app, lo stack indietro di supportFragmentManager deve essere vuoto, quindi il suo callback interno è disattivato.

Testare l'animazione del gesto Indietro predittivo

Se utilizzi ancora Android 13 o Android 14, puoi testare l'animazione di ritorno alla home mostrata nella Figura 1.

Per testare questa animazione, completa i seguenti passaggi:

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

2. Seleziona Animazioni predittive per Indietro.

3. Avvia l'app aggiornata e usa il gesto Indietro per vederla in azione.