Как добавить поддержку предпросмотра для жеста "Назад"

Рисунок 1. Макет предпросмотра для жеста "Назад" на телефоне

Предпросмотр для жеста "Назад" – это функция навигации жестами, которая позволяет пользователям увидеть, куда они перейдут, если проведут по экрану назад.

Например, при использовании жеста "Назад" может показываться анимированный предпросмотр главного экрана, расположенного за приложением, как показано на макете на рисунке 1.

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

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

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

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

Практическая работа и видео с конференции Google I/O

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

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

Как обрабатывать специальные жесты "Назад" в Compose

В Compose есть composable-функция 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 обратной навигации, на AndroidX API

Как перенести реализацию обратной навигации 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 на AndroidX API:

  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 обрабатывает обратную навигацию для извлечения целевых страниц из обратного стека, если предыдущие пользовательские обратные вызовы отключены.
  • Наконец, система обрабатывает жест "Назад", если все предыдущие обратные вызовы отключены. Когда стек возврата находится в корневом пункте назначения, система запускает системные анимации, например возврата на главный экран, перехода между объектами activity и перехода между задачами.

В приложениях на основе представлений действует тот же принцип: приоритет имеет последнее добавленное включенное значение OnBackPressedCallback, затем FragmentManager и, наконец, системная обработка кнопки "Назад".

Как протестировать анимацию для жеста "Назад"

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

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

  1. На устройстве выберите Настройки > Система > Для разработчиков.

  2. Выберите Анимации с предпросмотром для жеста "Назад".

  3. Запустите обновленное приложение и выполните жест "Назад", чтобы увидеть, как работает предпросмотр.