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

Рисунок 1. Макет, показывающий, как выглядит предпросмотр для жеста "Назад" на телефоне

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

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

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

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

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

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

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

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

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

Как обрабатывать собственные жесты "Назад" в 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 и как обрабатывает обратную навигацию.

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

Как перенести реализацию обратной навигации AndroidX

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

Чтобы API, которые уже используют OnBackPressedDispatcher (например, Fragments и Navigation Component), работали без проблем с предпросмотром для жеста "Назад", обновите 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 значение 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. Это создаст обратный вызов наблюдателя, который не использует событие возврата. Например, вы можете зарегистрировать этот обратный вызов, когда пользователь возвращается из корневого действия (выходит из приложения), чтобы зарегистрировать событие возврата или запустить бизнес-логику, по-прежнему позволяя воспроизводить анимацию возврата на главный экран.
  • В приложениях на основе View. Регистрируйте события в обратных вызовах жизненного цикла или обратного стека, а не используйте события возврата.
    • Для переходов между действиями проверьте, находится ли isFinishing в true в пределах Activity.onDestroy().
    • Для переходов между фрагментами проверьте, имеет ли isRemoving значение true в жизненном цикле представления фрагмента onDestroy(), или используйте FragmentManager.OnBackStackChangedListener (onBackStackChangeStarted/onBackStackChangeCommitted).

Создавайте обратные вызовы с одной задачей

В диспетчер можно добавить несколько обратных вызовов. Обратные вызовы добавляются в стек, в котором последний добавленный включенный обратный вызов обрабатывает следующий жест "Назад" (один обратный вызов на жест).

Управлять состоянием обратного вызова проще, если у него одна задача. Пример:

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

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

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

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

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

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

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

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

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

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