Aggiunta del supporto per il gesto Indietro predittivo

Android 14 (livello API 34) aggiunge il supporto per ulteriori animazioni di sistema e API per creare animazioni personalizzate. Per ulteriori informazioni, vedi Aggiunta del supporto per animazioni Indietro predittive integrate e personalizzate.

Ad esempio, l'utilizzo di un gesto Indietro può mostrare un'anteprima animata della schermata Home dietro l'app, come mostrato nel mockup in Figura 1. A partire da Android 13, puoi testa questa animazione di ritorno a casa attivando un'opzione sviluppatore (come descritto in questa pagina).

Il supporto del gesto Indietro predittivo richiede l'aggiornamento dell'app, utilizzando il compatibile con le versioni precedenti OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) o versioni successive, oppure tramite la nuova versione di OnBackInvokedCallback. tramite l'API Platform. La maggior parte delle app userà 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 arretrate di KeyEvent.KEYCODE_BACK ed eventuali classi con metodi onBackPressed come Activity e Dialog con le nuove API Indietro del sistema.

Video di codelab e Google I/O

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

Puoi anche guardare il nostro video Google I/O, che presenta altri esempi di che implementa AndroidX e le API della piattaforma.

Aggiornare un'app che utilizza la navigazione a ritroso predefinita

L'aggiornamento dell'app per supportare questa funzionalità è semplice se l'app non supporta implementare un comportamento Indietro personalizzato (in altre parole, lascia la gestione al sistema). Attiva questa funzionalità come descritto in guida.

Se la tua app utilizza Frammenti o il componente di navigazione, esegui anche l'upgrade a Attività di AndroidX 1.6.0-alpha05 o superiore.

Aggiornare un'app che utilizza la navigazione a ritroso personalizzata

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

Eseguire la migrazione di un'implementazione di 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 con gesti personalizzati con OnBackPressedDispatcher, come descritto in Fornire la navigazione a ritroso personalizzata.

Se la tua app rientra in questa categoria, svolgi i passaggi che seguono per aggiungere il supporto del gesto Indietro predittivo:

1. Per assicurarti che le API che utilizzano già le API OnBackPressedDispatcher (come Frammenti e il componente di navigazione) funzionano perfettamente con gesto Indietro predittivo, aggiorna a Attività di AndroidX 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"
   

2. Attiva il gesto Indietro predittivo, come descritto in su questa pagina.

Esegui la migrazione di un'app AndroidX che contiene 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 della schiena del sistema a quella di AndroidX OnBackPressedDispatcher con un'implementazione OnBackPressedCallback. Per indicazioni dettagliate, consulta Fornire la navigazione a ritroso personalizzata.

2. Disattiva OnBackPressedCallback quando vuoi smettere di intercettare la parte posteriore gesto.

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

4. Assicurati di eseguire l'upgrade a Attività di AndroidX 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"
   

5. Una volta eseguita correttamente la migrazione dell'app, attivare il gesto Indietro predittivo (come descritto nell'articolo questa pagina) per vedere l'animazione del sistema per il rientro a casa.

Esegui la migrazione di un'app che utilizza API di navigazione a ritroso non supportate alle API di piattaforma

Se la tua app non può utilizzare le librerie AndroidX e invece implementa o rende riferimento alla navigazione a ritroso personalizzata utilizzando API non supportate, devi eseguire la migrazione all'API della piattaforma OnBackInvokedCallback.

Per eseguire la migrazione delle API non supportate all'API della piattaforma, completa i seguenti passaggi:

1. Usa la nuova API OnBackInvokedCallback sui dispositivi con Android 13 o e di fare affidamento su API non supportate sui dispositivi con Android 12 o in basso.

2. Registra la tua logica di back-up personalizzata in OnBackInvokedCallback con onBackInvokedDispatcher. In questo modo l'attività corrente terminato e il callback ha la possibilità di reagire all'azione Indietro una volta l'utente completa la navigazione indietro del sistema.

3. Annulla la registrazione di OnBackInvokedCallback quando vuoi interrompere l'intercettazione gesto Indietro. In caso contrario, gli utenti potrebbero notare comportamenti indesiderati quando utilizzano un La navigazione a ritroso del sistema, ad esempio "bloccarsi" tra le visualizzazioni che forza 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 a ritroso tramite OnBackPressed o KeyEvent.KEYCODE_BACK per Android 13 e versioni successive.

5. Una volta eseguita correttamente la migrazione dell'app, attivare il gesto Indietro predittivo (come descritto nell'articolo questa pagina) in modo che OnBackInvokedCallback abbia effetto.

Puoi registrare un OnBackInvokedCallback con PRIORITY_DEFAULT o PRIORITY_OVERLAY, che non è disponibile nell'analogo AndroidX OnBackPressedCallback. La registrazione di una richiamata con PRIORITY_OVERLAY è utile in alcuni casi. Questo potrebbe essere applicabile quando esegui la migrazione da onKeyPreIme() e il callback deve ricevere il gesto Indietro di un IME aperto. Gli IME registrano i callback con PRIORITY_DEFAULT all'apertura. Registra la richiamata con PRIORITY_OVERLAY per assicurarti OnBackInvokedDispatcher invia il gesto Indietro al callback dell'IME aperto.

Attiva il gesto Indietro predittivo

Una volta stabilito come aggiornare l'app in base al tuo caso, attiva supportando il gesto Indietro predittivo.

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

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

Se non specifichi un valore, il valore predefinito è false e:

• Disattiva l'animazione di sistema dei gesti Indietro predittivi.
• Ignora OnBackInvokedCallback, ma OnBackPressedCallback chiamate continuare a lavorare.

Attivazione a livello di attività

A partire da Android 14, il flag android:enableOnBackInvokedCallback consente attivi le animazioni di sistema predittive a livello di attività. Questo comportamento rende più gestibile la migrazione di app multiattività di grandi dimensioni a gesti Indietro.

Il seguente codice mostra un esempio di utilizzo di enableOnBackInvokedCallback 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>

Nell'esempio precedente, l'impostazione android:enableOnBackInvokedCallback=true per ".SecondActivity" attiva l'animazione di sistema tra attività.

Quando utilizzi il comando android:enableOnBackInvokedCallback flag:

• L'impostazione di android:enableOnBackInvokedCallback=false disattiva la funzionalità Indietro predittiva le animazioni in corrispondenza dell'attività o a livello di app, a seconda di dove hai impostato il tag, e indica al sistema ignori le chiamate all'API della piattaforma OnBackInvokedCallback. Tuttavia, le chiamate al numero OnBackPressedCallback continuano a essere eseguite perché OnBackPressedCallback è compatibile con le versioni precedenti e chiama 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 predefinito per attività impostando il flag a livello di attività, come mostrato in nell'esempio di codice precedente.

Best practice per il callback

Di seguito sono riportate le best practice per l'utilizzo dei callback di sistema supportati:BackHandler (per Componi), OnBackPressedCallback oOnBackInvokedCallback.

Determina lo stato dell'interfaccia utente che abilita e disabilita ogni callback

Stato UI è una proprietà che descrive l'interfaccia utente. Ti consigliamo di seguire le best practice passaggi.

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

2. Definisci lo stato utilizzando un titolare dei dati osservabile tipo, ad esempio StateFlow o Scrivi lo stato e attiva o disattiva il callback quando lo stato cambia.

Se in precedenza l'app associava la logica di nuovo alle istruzioni condizionali, Ciò potrebbe significare che stai reagendo all'evento "back" dopo che è stato già verificato: un pattern che dovresti evitare con i callback più recenti. Se possibile, sposta il callback al di fuori dell'istruzione condizionale e associare il callback a un tipo di titolare dei dati osservabile.

Usa i callback del sistema per la logica UI

Logica UI indica come visualizzare la UI. Utilizza i callback del sistema per eseguire la logica dell'interfaccia utente, ad esempio mostrare un popup o eseguire un'animazione.

Se l'app attiva un callback di sistema, le animazioni predittive non vengono eseguite e devi gestire l'evento Indietro. Non creare callback solo per eseguire non UI logica.

Ad esempio, se stai intercettando gli eventi solo per registrare, registra all'interno della Attività o Ciclo di vita di un frammento.

• Per i casi da attività ad attività o da frammento ad attività, registra se isFinishing in onDestroy è true nel ciclo di vita dell'attività.
• Per i casi da frammento a frammento, registra se isRemoving in onDestroy è true all'interno del ciclo di vita della vista Framment; oppure accedi utilizzando onBackStackChangeStarted o onBackStackChangeCommitted in FragmentManager.OnBackStackChangedListener.

Per la richiesta Compose, accedi al callback onCleared() di una ViewModel associate alla destinazione Compose. Questo è il segnale migliore per sapere quando una destinazione di composizione è stata rimossa dallo stack precedente ed eliminata.

Crea callback di responsabilità singola

Questo è possibile perché puoi aggiungere più callback al supervisore. I callback vengono aggiunti a uno stack in cui è stato aggiunto l'ultimo callback abilitato gestisce il gesto Indietro successivo con un callback per ogni gesto Indietro.

Testa l'animazione del gesto Indietro predittivo

A partire dalla release finale di Android 13, dovresti essere in grado di attivare una opzione sviluppatore per testare l'animazione per il rientro a casa mostrata nella Figura 1.

Per testare questa animazione, procedi nel seguente modo:

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

2. Seleziona Animazioni Indietro predittive.

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