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

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

Predictive Back, функция навигации с помощью жестов, позволяет пользователям предварительно просматривать, куда их приведет смахивание назад.

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

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

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

Для поддержки предиктивного жеста назад необходимо обновить приложение с помощью обратно совместимого API OnBackPressedCallback AppCompat 1.6.0-alpha05 (AndroidX) или более поздней версии или с помощью нового API платформы OnBackInvokedCallback . Большинство приложений используют обратно совместимый API AndroidX.

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

Видео Codelab и Google I/O

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

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

Обновите приложение, которое использует обратную навигацию по умолчанию.

Обновить приложение для поддержки этой функции несложно, если ваше приложение не реализует какое-либо настраиваемое обратное поведение (другими словами, оно оставляет обработку обратной связи на усмотрение системы). Включите эту функцию , как описано в этом руководстве.

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

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

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

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

Перенос реализации обратной навигации AndroidX

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

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

  1. Чтобы гарантировать, что API, которые уже используют API OnBackPressedDispatcher (например, фрагменты и компонент навигации), беспрепятственно работают с прогнозирующим жестом назад, обновите 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. Включите интеллектуальный жест назад , как описано на этой странице.

Перенесите приложение 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-alpha05 .

    // In your build.gradle file:
dependencies {

// Add this in addition to your other dependencies
implementation "androidx.activity:activity:1.6.0-alpha05"

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

Перенесите приложение, использующее неподдерживаемые API обратной навигации, на API платформы.

Если ваше приложение не может использовать библиотеки AndroidX и вместо этого реализует или ссылается на пользовательскую навигацию «Назад» с использованием неподдерживаемых API, вам необходимо перейти на API платформы OnBackInvokedCallback .

Выполните следующие шаги, чтобы перенести неподдерживаемые API на API платформы:

  1. Используйте новый API OnBackInvokedCallback на устройствах под управлением Android 13 или более поздней версии и используйте неподдерживаемые API на устройствах под управлением Android 12 или более ранней версии.

  2. Зарегистрируйте свою пользовательскую обратную логику в OnBackInvokedCallback с помощью onBackInvokedDispatcher . Это предотвращает завершение текущего действия, и ваш обратный вызов получает возможность отреагировать на действие «Назад», как только пользователь завершит системную навигацию «Назад».

  3. Отмените регистрацию OnBackInvokedCallback , когда будете готовы прекратить перехват жеста назад. В противном случае пользователи могут столкнуться с нежелательным поведением при использовании системы «Назад» — например, «застреванием» между представлениями и принуждением их принудительно закрыть приложение.

    Вот пример того, как перенести логику из onBackPressed :

    Котлин 

    @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)
             */
        }
    }
}

    Ява

    @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. Прекратите перехват обратных событий через OnBackPressed или KeyEvent.KEYCODE_BACK для Android 13 и более поздних версий.

  5. После успешного переноса приложения включите предиктивный жест возврата (как описано на этой странице), чтобы OnBackInvokedCallback вступил в силу.

Вы можете зарегистрировать OnBackInvokedCallback с помощью PRIORITY_DEFAULT или PRIORITY_OVERLAY , который недоступен в аналогичном AndroidX OnBackPressedCallback . Регистрация обратного вызова с помощью PRIORITY_OVERLAY может оказаться полезной в некоторых случаях.

Это применимо, когда вы переходите с onKeyPreIme() и ваш обратный вызов должен получать жест возврата вместо открытого IME. IME регистрируют обратные вызовы с PRIORITY_DEFAULT при открытии. Зарегистрируйте обратный вызов с помощью PRIORITY_OVERLAY чтобы OnBackInvokedDispatcher отправлял жест возврата в обратный вызов вместо открытого IME.

Включите интеллектуальный жест назад

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

Чтобы принять участие, в AndroidManifest.xml в теге <application> установите для флага android:enableOnBackInvokedCallback значение true .

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

Если вы не укажете значение, оно по умолчанию будет равно false и выполняет следующие действия:

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

Согласие на уровне активности

Начиная с Android 14, флаг android:enableOnBackInvokedCallback позволяет вам включить прогнозируемую системную анимацию на уровне активности. Такое поведение делает более управляемым переход больших приложений с несколькими действиями на интеллектуальные жесты назад. В Android 15 функция прогнозирования больше не является приоритетом для разработчиков. Приложения могут включить прогнозирование полностью или на уровне активности.

В следующем коде показан пример использования 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=true для ".SecondActivity" включает системную анимацию перекрестных действий.

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

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

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

Ниже приведены рекомендации по использованию поддерживаемых системных обратных вызовов; BackHandler (для Compose), OnBackPressedCallback или OnBackInvokedCallback .

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

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

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

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

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

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

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

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

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

  • Для случаев «действия-действия» или «фрагмент-действия» регистрируйте, имеет ли isFinishing в onDestroy значение true в течение жизненного цикла действия.
  • Для случаев перехода от фрагмента к фрагменту регистрируйте, если isRemoving внутри onDestroy имеет значение true в течение жизненного цикла представления фрагмента. Или войдите в систему, используя методы onBackStackChangeStarted или onBackStackChangeCommitted в FragmentManager.OnBackStackChangedListener .

В случае Compose войдите в обратный вызов onCleared() ViewModel связанной с местом назначения Compose. Это лучший сигнал, позволяющий узнать, когда пункт назначения вытаскивается из заднего стека и уничтожается.

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

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

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

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

На рис. 2 показано, как можно иметь в стеке несколько обратных вызовов, каждый из которых отвечает за что-то одно. Обратный вызов выполняется только в том случае, если обратные вызовы над ним в стеке отключены. В этом примере обратный вызов «Вы уверены...» включается, когда пользователь вводит данные в форму, и отключается в противном случае. Обратный вызов открывает диалоговое окно подтверждения, когда пользователь проводит назад, чтобы выйти из формы.

Другой обратный вызов может включать в себя материальный компонент, поддерживающий обратный вызов с прогнозированием, переход AndroidX с использованием API-интерфейсов Progress или другой настраиваемый обратный вызов.

Обратный вызов childFragmentManager выполняется, если указанные выше обратные вызовы отключены и обратный стек для этого FragmentManager не пуст, где childFragmentManager прикреплен внутри фрагмента. В этом примере этот внутренний обратный вызов отключен.

Аналогично, внутренний обратный вызов supportFragmentManager выполняется, если вышеуказанные обратные вызовы отключены и его стек не пуст. Это поведение соответствует при использовании FragmentManager или NavigationComponent для навигации, поскольку NavigationComponent использует FragmentManager . В этом примере этот обратный вызов выполняется, если пользователь не ввел текст в форму, что привело к отключению обратного вызова «Вы уверены...».

Наконец, super.onBackPressed() — это обратный вызов системного уровня, который снова запускается, если вышеуказанные обратные вызовы отключены. Чтобы вызвать системную анимацию, такую ​​как возвращение домой, перекрестную активность и перекрестную задачу, задний стек supportFragmentManager должен быть пустым, поэтому его внутренний обратный вызов отключен.

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

Если вы все еще используете Android 13 или Android 14, вы можете протестировать анимацию возвращения домой, показанную на рис. 1.

Чтобы протестировать эту анимацию, выполните следующие шаги:

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

  2. Выберите «Прогнозирующая анимация спины» .

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