Добавить поддержку интеллектуального жеста назад.

Рисунок 1. Макет интерфейса и функциональности прогнозируемого жеста «Назад» на телефоне.

Функция «Предиктивная навигация назад» (Predictive Back), использующая жесты, позволяет пользователям предварительно просмотреть, куда их перенесет жест «назад».

Например, с помощью жеста «назад» можно отобразить анимированный предварительный просмотр главного экрана, расположенного за вашим приложением, как показано на макете на рисунке 1.

Начиная с Android 15, опция разработчика для анимаций возврата назад больше недоступна. Системные анимации, такие как возврат на главный экран, анимация при переходе между задачами и действиями, теперь отображаются для приложений, которые полностью или частично включили функцию прогнозирования жеста возврата назад.

Вы можете протестировать эту анимацию возврата на главную страницу (как описано в следующем разделе этой страницы).

Для поддержки предиктивного жеста «назад» необходимо обновить приложение, использовать обратно совместимый API OnBackPressedCallback из AndroidX Activity 1.6.0 или выше, либо использовать новый API платформы OnBackInvokedCallback . Большинство приложений используют обратно совместимый API AndroidX.

Это обновление предоставляет путь миграции для корректного перехвата перехода назад, который включает замену перехвата перехода назад из KeyEvent.KEYCODE_BACK и любых классов с методами onBackPressed , таких как Activity и Dialog на новые системные API для перехода назад.

Видео Codelab и Google I/O

Помимо использования документации на этой странице, попробуйте наш практический пример . Он демонстрирует распространенный сценарий использования WebView для обработки предиктивного жеста «назад» с помощью API AndroidX Activity.

Вы также можете посмотреть наше видео с Google I/O, в котором представлены дополнительные примеры реализации AndroidX и API платформы.

Обработка пользовательских жестов «назад» в Compose.

Compose предоставляет компонент PredictiveBackHandler для обработки пользовательских жестов возврата назад. Этот API позволяет реагировать на жест возврата назад и предоставляет Flow объектов BackEventCompat , которые можно использовать для реализации пользовательских анимаций или переходов при свайпе пользователя.

Для использования PredictiveBackHandler убедитесь, что ваше приложение включает зависимость androidx.activity:activity-compose (версия 1.8.0 или выше):

// In your build.gradle.kts file:
dependencies {
    implementation("androidx.activity:activity-compose:1.8.0")
}


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

Если вам нужно перехватить только жест "назад" без отслеживания прогресса, используйте BackHandler .

Обновите приложение, использующее стандартную навигацию «Назад».

Функция предиктивного ответа включена по умолчанию.

Если ваше приложение использует фрагменты или компонент навигации, обновите AndroidX Activity до версии 1.6.0 или выше.

Обновите приложение, использующее пользовательскую навигацию "Назад".

Если ваше приложение реализует пользовательское поведение возврата назад, существуют разные пути миграции в зависимости от того, использует ли оно AndroidX и как обрабатывает навигацию назад.

Как ваше приложение обрабатывает возврат к предыдущему экрану Рекомендуемый путь миграции (ссылка на этой странице)
API AndroidX Перенести существующую реализацию AndroidX на задний план.
Неподдерживаемые API платформы Перенесите приложение AndroidX, содержащее неподдерживаемые API для навигации назад, на API AndroidX.

Перенести реализацию навигации "назад" из AndroidX.

Этот вариант использования является наиболее распространенным (и наиболее рекомендуемым). Он применим к новым или существующим приложениям, которые реализуют пользовательскую обработку навигации жестами с помощью OnBackPressedDispatcher , как описано в разделе «Предоставление пользовательской навигации назад» .

Чтобы обеспечить бесперебойную работу API, уже использующих OnBackPressedDispatcher (таких как фрагменты и компонент навигации), с предиктивным жестом «назад», обновите AndroidX Activity до версии 1.6.0 или выше.

// In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

Перенесите приложение AndroidX, содержащее неподдерживаемые API для навигации назад, на API AndroidX.

Если ваше приложение использует библиотеки AndroidX, но реализует или ссылается на неподдерживаемые API для навигации назад, вам потребуется перейти на использование API AndroidX для поддержки нового поведения.

Для переноса неподдерживаемых API на API AndroidX:

  1. Перенесите логику обработки возврата в вашей системе в OnBackPressedDispatcher из AndroidX с реализацией OnBackPressedCallback . Подробные инструкции см. в разделе «Предоставление пользовательской навигации назад» .

  2. Отключите функцию OnBackPressedCallback , когда будете готовы прекратить перехват жеста "назад".

  3. Прекратите перехватывать события возврата с помощью OnBackPressed или KeyEvent.KEYCODE_BACK .

  4. Обязательно обновите AndroidX Activity до версии 1.6.0 или выше.

    // In your build.gradle file:
dependencies {
    // Add this in addition to your other dependencies
    implementation "androidx.activity:activity:1.6.0"
}

Отказаться от функции прогнозирования результатов

Чтобы отказаться от этого, в файле AndroidManifest.xml , в теге <application> , установите флаг android:enableOnBackInvokedCallback в false .

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

Установка этого параметра в значение false приводит к следующему результату:

  • Отключает анимацию системы прогнозирования жестов при движении назад.
  • Игнорирует OnBackInvokedCallback , но вызовы OnBackPressedCallback продолжают работать.

Отказаться от участия на уровне активности

Флаг android:enableOnBackInvokedCallback позволяет отказаться от предиктивной системной анимации на уровне активности. Такое поведение упрощает миграцию больших приложений с несколькими активностями на предиктивные жесты возврата.

Приведенный ниже код демонстрирует пример использования параметра enableOnBackInvokedCallback для включения системной анимации возврата на главный экран из MainActivity :

<manifest ...>
    <application . . .

        android:enableOnBackInvokedCallback="false">

        <activity
            android:name=".MainActivity"
            android:enableOnBackInvokedCallback="true"
            ...
        </activity>
        <activity
            android:name=".SecondActivity"
            android:enableOnBackInvokedCallback="false"
            ...
        </activity>
    </application>
</manifest>

При использовании флага android:enableOnBackInvokedCallback следует учитывать следующие моменты:

  • Установка параметра android:enableOnBackInvokedCallback=false отключает анимацию «назад» с функцией прогнозирования либо на уровне активности, либо на уровне приложения, в зависимости от того, где вы задали этот тег, и указывает системе игнорировать вызовы API платформы OnBackInvokedCallback . Однако вызовы OnBackPressedCallback продолжают выполняться, поскольку OnBackPressedCallback обратно совместим и вызывает API onBackPressed , который не поддерживается до Android 13.
  • Установка флага enableOnBackInvokedCallback на уровне приложения задает значение по умолчанию для всех действий в приложении. Вы можете переопределить значение по умолчанию для каждого действия, установив флаг на уровне действия, как показано в приведенном выше примере кода.

Рекомендации по обратному звонку

При использовании поддерживаемых системных обработчиков обратного вызова следуйте этим рекомендациям: PredictiveBackHandler или BackHandler ( для Compose ), OnBackPressedCallback или OnBackInvokedCallback .

Определите состояние пользовательского интерфейса, которое включает и отключает каждый обратный вызов.

Состояние пользовательского интерфейса — это свойство, описывающее пользовательский интерфейс. Мы рекомендуем выполнить следующие основные шаги.

  1. Определите состояние пользовательского интерфейса, которое включает и отключает каждый обратный вызов.

  2. Определите это состояние, используя наблюдаемый тип данных , например StateFlow или Compose State, и включайте или отключайте функцию обратного вызова по мере изменения состояния.

Если в вашем приложении ранее логика возврата в исходное состояние связывалась с условными операторами, это может означать, что вы реагируете на событие возврата после того, как оно уже произошло. Избегайте этого шаблона в новых коллбэках. По возможности, вынесите коллбэк за пределы условного оператора и вместо этого свяжите его с наблюдаемым типом данных.

Используйте системные обратные вызовы для логики пользовательского интерфейса.

Логика пользовательского интерфейса определяет, как его отображать. Используйте системные обратные вызовы для выполнения логики пользовательского интерфейса, например, для отображения диалогового окна или запуска анимации.

Если в вашем приложении включена функция OnBackPressedCallback или OnBackInvokedCallback с PRIORITY_DEFAULT или PRIORITY_OVERLAY , анимация возврата назад не будет выполняться, и вам необходимо будет обработать событие возврата. Не создавайте эти функции обратного вызова для выполнения бизнес-логики или для логирования.

Если вашему приложению необходимо выполнять бизнес-логику или регистрировать события, когда пользователь смахивает назад, используйте следующие подходы:

  • В Compose: В методе onCleared() ViewModel , связанного с целевым объектом Compose, следует регистрировать события. Это лучший способ узнать, когда целевой объект Compose удаляется из стека и уничтожается.
  • На Android 16 и выше: используйте OnBackInvokedCallback с PRIORITY_SYSTEM_NAVIGATION_OBSERVER . Это создаст обратный вызов наблюдателя, который не обрабатывает событие возврата. Например, вы можете зарегистрировать этот обратный вызов, когда пользователь проводит пальцем назад от корневой активности (покидавая ваше приложение), чтобы зарегистрировать событие возврата или выполнить бизнес-логику, при этом позволяя воспроизводиться анимации возврата на главный экран.
  • В приложениях, основанных на представлениях: ведите логи внутри коллбэков жизненного цикла или стека возврата, а не обрабатывайте события возврата:
    • Для переходов между активностями проверяйте, имеет ли значение isFinishing true внутри Activity.onDestroy() .
    • Для переходов между фрагментами проверьте, имеет ли isRemoving значение true в рамках жизненного цикла представления фрагмента onDestroy() , или используйте FragmentManager.OnBackStackChangedListener ( onBackStackChangeStarted / onBackStackChangeCommitted ).

Создайте обратные вызовы с единственной обязанностью.

К диспетчеру можно добавить несколько функций обратного вызова. Функции обратного вызова добавляются в стек, в котором последняя добавленная включенная функция обрабатывает следующий жест "назад", при этом для каждого жеста "назад" используется одна функция обратного вызова.

Управлять состоянием активности функции обратного вызова проще, если эта функция выполняет единственную задачу. Например:

Порядок вызова функций обратного вызова в стеке в Compose.
Рисунок 2. Диаграмма стека обратных вызовов в Compose.

На рисунке 2 показано, как можно иметь несколько коллбэков в стеке, каждый из которых отвечает за что-то одно. В Compose коллбэки выполняются от самого внутреннего к самому внешнему компонуемому объекту, и коллбэк выполняется только в том случае, если предшествующие ему коллбэки в стеке отключены:

  • Функция PredictiveBackHandler "Вы уверены..." включается, когда пользователь вводит данные в форму, и отключается в остальных случаях. При включении она перехватывает жест "назад" для отображения диалогового окна подтверждения или пользовательской анимации в приложении.
  • BackHandler на уровне экрана срабатывает, если предыдущий обратный вызов отключен. В этом примере он отключен.
  • Функция обратного вызова NavHost обрабатывает возврат к предыдущим позициям для извлечения пунктов назначения из стека возврата, если предыдущие пользовательские функции обратного вызова отключены.
  • Наконец, система обрабатывает жест "назад", если все предыдущие обратные вызовы отключены. Когда стек возврата достигает своего корневого пункта назначения, система запускает системные анимации, такие как возврат на главный экран, анимация между различными активностями и задачами.

Аналогичное поведение стека применяется и в приложениях, основанных на представлениях: последний добавленный включенный OnBackPressedCallback имеет приоритет, переключаясь на FragmentManager и, в конечном итоге, на системную обработку возврата.

Протестируйте анимацию предиктивного жеста «назад».

Начиная с Android 15, системные анимации, такие как возврат на главный экран, анимация между задачами и действиями, включены по умолчанию для приложений, поддерживающих предиктивную навигацию назад. Теперь они доступны только разработчикам.

На устройствах под управлением Android 13 или Android 14 можно включить параметры разработчика, чтобы протестировать анимацию возврата на главный экран, показанную на рисунке 1:

  1. На вашем устройстве перейдите в Настройки > Система > Параметры разработчика .

  2. Выберите «Предиктивная анимация спины» .

  3. Запустите обновлённое приложение и используйте жест «назад», чтобы увидеть его в действии.