Aggiunta del supporto per il gesto Indietro predittivo

Figura 1. Simulazione dell'aspetto e del design predittivi del gesto Indietro su uno smartphone

Android 14 (livello API 34) aggiunge il supporto di API e animazioni di sistema aggiuntive per creare animazioni personalizzate. Per scoprire di più, consulta Aggiungere il supporto delle animazioni predittive integrate e personalizzate.

Ad esempio, con il gesto Indietro puoi visualizzare un'anteprima animata della schermata Home dietro l'app, come presentato nel modello nella figura 1. A partire da Android 13, puoi testare questa animazione back-to-home attivando un'opzione sviluppatore (come descritto in questa pagina).

Il supporto del gesto Indietro predittivo richiede l'aggiornamento dell'app, l'utilizzo dell'API OnBackPressedCallback AppCompat 1.6.0-alpha05 compatibile con le versioni precedenti (AndroidX) o versioni successive oppure la nuova API della piattaforma OnBackInvokedCallback. La maggior parte delle app utilizzerà l'API AndroidX compatibile con le versioni precedenti.

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

Codelab e video Google I/O

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

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

Aggiornare un'app che utilizza la navigazione indietro predefinita

L'aggiornamento dell'app per supportare questa funzionalità è semplice se l'app non implementa alcun comportamento indietro personalizzato (in altre parole, la gestione rimane invariata al sistema). Attiva questa funzionalità come descritto in questa guida.

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

Aggiornare un'app che utilizza una navigazione a ritroso personalizzata

Se la tua app implementa un comportamento indietro personalizzato, esistono percorsi di migrazione diversi a seconda dell'utilizzo o meno di AndroidX e di come gestisce la navigazione a ritroso.

La tua app utilizza AndroidX In che modo l'app gestisce la navigazione a ritroso Percorso di migrazione consigliato (link in questa pagina)
API AndroidX Eseguire la migrazione di un'implementazione precedente di AndroidX esistente
API della piattaforma non supportate Eseguire la migrazione alle API AndroidX di un'app AndroidX contenente API di navigazione indietro non supportate
No API della piattaforma non supportate, in grado di eseguire la migrazione Eseguire la migrazione di un'app che utilizza API di navigazione indietro non supportate alle API della piattaforma
API della piattaforma non supportate, ma di cui non è possibile eseguire la migrazione Rimanda l'attivazione finché questa funzionalità non diventerà obbligatoria

Eseguire la migrazione di un'implementazione della navigazione indietro su 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.

Se la tua app rientra in questa categoria, segui questi passaggi per aggiungere il supporto per il gesto Indietro predittivo:

  1. Per assicurarti che le API che usano già le API 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-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 questa pagina.

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

Se la tua app utilizza le librerie AndroidX, ma implementa o fa riferimento alle API di navigazione posteriore non supportate, dovrai eseguire la migrazione alle 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 indietro del tuo sistema ad AndroidX OnBackPressedDispatcher con un'implementazione di OnBackPressedCallback. Per indicazioni dettagliate, consulta Fornire una navigazione a ritroso personalizzata.

  2. Disabilita OnBackPressedCallback quando è tutto pronto per interrompere l'intercettazione del backgesture.

  3. Non intercettare più eventi 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"
    
  5. Una volta eseguita correttamente la migrazione dell'app, attiva il gesto Indietro predittivo (come descritto in questa pagina) per visualizzare l'animazione del sistema per il ripristino della schermata Home.

Eseguire 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 invece implementa o fa riferimento a una navigazione posteriore personalizzata utilizzando le API non supportate, devi eseguire la migrazione all'API della piattaforma OnBackInvokedCallback.

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 utilizza le API non supportate sui dispositivi con Android 12 o versioni precedenti.

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

  3. Annulla la registrazione del OnBackInvokedCallback quando è tutto pronto per interrompere l'intercettazione del gesto Indietro. In caso contrario, gli utenti potrebbero riscontrare comportamenti indesiderati quando utilizzano una navigazione a ritroso del sistema, ad esempio "bloccarsi" tra le visualizzazioni e 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. Non intercettare più eventi precedenti tramite OnBackPressed o KeyEvent.KEYCODE_BACK per Android 13 e versioni successive.

  5. Una volta eseguita correttamente la migrazione dell'app, attiva il gesto Indietro predittivo (come descritto in questa pagina) in modo che OnBackInvokedCallback venga applicato.

Puoi registrare un OnBackInvokedCallback con PRIORITY_DEFAULT o PRIORITY_OVERLAY, che non è disponibile su un AndroidX simile OnBackPressedCallback. La registrazione di un callback con PRIORITY_OVERLAY è utile in alcuni casi. Questo potrebbe verificarsi quando esegui la migrazione da onKeyPreIme() e il callback deve ricevere il gesto Indietro anziché un IME aperto. Gli IME registrano i callback con PRIORITY_DEFAULT quando vengono aperti. Registra il callback con PRIORITY_OVERLAY per assicurarti che OnBackInvokedDispatcher invii il gesto Indietro al callback anziché l'IME aperto.

Attiva il gesto Indietro predittivo

Dopo aver stabilito come aggiornare l'app in base alla tua richiesta, attiva il supporto del gesto Indietro predittivo.

Per l'attivazione, in AndroidManifest.xml, nel tag <application>, imposta il flag android:enableOnBackInvokedCallback su true.

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

Se non specifichi un valore, il valore predefinito sarà false e:

  • Disattiva l'animazione del sistema predittivo dei gesti Indietro.
  • Ignora OnBackInvokedCallback, ma le chiamate OnBackPressedCallback continuano a funzionare.

Attivazione a livello di attività

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

Il seguente codice mostra un esempio di utilizzo di enableOnBackInvokedCallback per attivare l'animazione di sistema per il rientro a casa 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 di android:enableOnBackInvokedCallback=true per ".SecondActivity" consente di attivare l'animazione del sistema cross-attività.

Quando utilizzi il flag android:enableOnBackInvokedCallback, tieni presente quanto segue:

  • L'impostazione android:enableOnBackInvokedCallback=false comporta la disattivazione delle animazioni retro predittive 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 nelle versioni precedenti ad Android 13.
  • L'impostazione del flag enableOnBackInvokedCallback a livello di app stabilisce il valore predefinito per tutte le attività nell'app. Puoi ignorare il flag predefinito per attività impostando il flag a livello di attività, come mostrato 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 Compose), OnBackPressedCallback o OnBackInvokedCallback.

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

Lo stato UI è una proprietà che descrive l'interfaccia utente. Ti consigliamo di seguire questi passaggi generali.

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

  2. Definisci questo stato utilizzando un tipo di titolare dati osservabile, come StateFlow o Compose State, e abilita o disabilita il callback quando cambia lo stato.

Se in precedenza la tua app associava una logica indietro alle istruzioni condizionali, questo potrebbe significare che stai reagendo all'evento back dopo che si è già verificato, un pattern che dovresti evitare con i callback più recenti. Se possibile, sposta il callback al di fuori dell'istruzione condizionale e associalo a un tipo di titolare dati osservabile.

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

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

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

Ad esempio, se intercettano eventi indietro solo per registrarli, accedi al ciclo di vita Attività o Frammento.

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

Per la richiesta di Compose, accedi al callback onCleared() di un ViewModel associato alla destinazione Compose. Questo è l'indicatore migliore per sapere quando una destinazione di scrittura è stata rimossa dallo stack precedente ed è stata eliminata.

Crea callback di responsabilità singola

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

Testa l'animazione predittiva del gesto Indietro

A partire dalla release finale di Android 13, dovresti essere in grado di abilitare un'opzione sviluppatore per testare l'animazione back-to-home mostrata nella Figura 1.

Per testare l'animazione, procedi nel seguente modo:

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

  2. Seleziona Animazioni predittive indietro.

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