![](https://developer.android.com/static/images/about/versions/13/predictive-back-nav-home.gif?authuser=8&hl=it)
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) |
Sì | 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:
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"
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:
Esegui la migrazione della logica di gestione indietro del tuo sistema ad AndroidX
OnBackPressedDispatcher
con un'implementazione diOnBackPressedCallback
. Per indicazioni dettagliate, consulta Fornire una navigazione a ritroso personalizzata.Disabilita
OnBackPressedCallback
quando è tutto pronto per interrompere l'intercettazione del backgesture.Non intercettare più eventi tramite
OnBackPressed
oKeyEvent.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"
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:
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.Registra la tua logica di back personalizzata in
OnBackInvokedCallback
cononBackInvokedDispatcher
. 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.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) */ } ); } }
Non intercettare più eventi precedenti tramite
OnBackPressed
oKeyEvent.KEYCODE_BACK
per Android 13 e versioni successive.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 chiamateOnBackPressedCallback
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 piattaformaOnBackInvokedCallback
. Tuttavia, le chiamate aOnBackPressedCallback
continuano a essere eseguite perchéOnBackPressedCallback
è compatibile con le versioni precedenti e chiama l'APIonBackPressed
, 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.
Determina lo stato dell'interfaccia utente che attiva e disattiva ogni callback.
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
inonDestroy
ètrue
all'interno del ciclo di vita dell'attività. - Per i casi da frammento a frammento, registra se
isRemoving
inonDestroy
è true all'interno del ciclo di vita di visualizzazione del frammento; oppure, registra utilizzando i metodionBackStackChangeStarted
oonBackStackChangeCommitted
inFragmentManager.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:
Sul dispositivo, vai a Impostazioni > Sistema > Opzioni sviluppatore.
Seleziona Animazioni predittive indietro.
Avvia l'app aggiornata e utilizza il gesto Indietro per vederla in azione.