Поддержка вырезов дисплея

Попробуйте способ создания композиций.
Jetpack Compose — рекомендуемый набор инструментов для создания пользовательского интерфейса для Android. Узнайте, как работать с вырезами на экране в Compose.
Отображение вырезанных элементов в меню «Составить» →

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

Android поддерживает вырезы в экране на устройствах под управлением Android 9 (уровень API 28) и выше. Однако производители устройств также могут поддерживать вырезы в экране на устройствах под управлением Android 8.1 или ниже.

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

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

Выберите способ обработки вырезанных областей в вашем приложении.

Если вы не хотите, чтобы ваш контент перекрывал область выреза, обычно достаточно убедиться, что ваш контент не перекрывает строку состояния и панель навигации. Если вы выполняете рендеринг в область выреза, используйте WindowInsetsCompat.getDisplayCutout() чтобы получить объект DisplayCutout , содержащий безопасные отступы и ограничивающую рамку для каждого выреза. Эти API позволяют проверить, перекрывает ли ваш контент область выреза, чтобы при необходимости изменить его положение.

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

  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT : содержимое отображается в области выреза, если область выреза находится в системной панели. В противном случае окно не перекрывает область выреза; например, содержимое может быть с черными полосами сверху и снизу при отображении в альбомном режиме. Если ваше приложение ориентировано на SDK 35, это интерпретируется как ALWAYS для неплавающих окон.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS : содержимому всегда разрешается выходить за пределы областей выреза. Если ваше приложение ориентировано на SDK 35 и работает на устройстве Android 15, это единственный разрешенный режим для неплавающих окон, обеспечивающий отображение от края до края.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES : содержимое отображается в вырезанной области как в портретном, так и в альбомном режимах. Не использовать для плавающих окон. Если ваше приложение ориентировано на SDK 35, это значение интерпретируется как ALWAYS для неплавающих окон.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER : содержимое никогда не отображается в области выреза. Если ваше приложение ориентировано на SDK 35, это интерпретируется как ALWAYS для неплавающих окон.

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

<style name="ActivityTheme">
  <item name="android:windowLayoutInDisplayCutoutMode">
    shortEdges <!-- default, shortEdges, or never -->
  </item>
</style>

В следующих разделах более подробно описаны различные режимы вырезания.

Поведение по умолчанию

Если ваше приложение ориентировано на SDK 35 и работает на устройстве Android 15, то LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS является поведением по умолчанию, а LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT интерпретируется как LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS для неплавающих окон.

В противном случае по умолчанию используется значение LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT .

Отображение контента в областях с короткими краями выреза.

Если ваше приложение ориентировано на SDK 35 и работает на устройстве Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES интерпретируется как LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS для неплавающих окон.

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

На следующем изображении представлен пример параметра LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES для устройства в портретном режиме:

Изображение, демонстрирующее отрисовку контента в вырезанной области в портретном режиме.
Рисунок 2. Отображение контента в вырезанной области в портретном режиме.

На следующем изображении представлен пример параметра LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES для устройства в альбомной ориентации:

Изображение, демонстрирующее отображение контента в вырезанной области в альбомном режиме.
Рисунок 3. Отображение контента в вырезанной области в альбомном режиме.

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

Вырез в углу считается расположенным на короткой стороне:

Изображение устройства с угловым вырезом.
Рисунок 4. Устройство с угловым вырезом.

Никогда не отображайте контент в области, вырезанной для отображения.

Если ваше приложение ориентировано на SDK 35 и работает на устройстве Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER интерпретируется как LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS для неплавающих окон.

При использовании LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER окно никогда не перекрывает область выреза.

Ниже приведён пример использования параметра LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER в портретном режиме:

Изображение, демонстрирующее режим LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER для портретной ориентации.
Рисунок 5. Пример параметра LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER для портретного режима.

Ниже приведён пример использования параметра LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER в альбомном режиме:

Изображение, демонстрирующее режим LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER для альбомной ориентации.
Рисунок 6. Пример режима LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER в альбомной ориентации.

Рекомендации по использованию вырезов в дисплеях.

При работе с декоративными вырезами следует учитывать следующее:

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

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

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

  • Используйте View.getLocationInWindow() , чтобы определить, сколько места в окне занимает ваше приложение. Не предполагайте, что приложение использует всё окно целиком, и не используйте View.getLocationOnScreen() .

  • Используйте режимы вырезания always , shortEdges или never если вашему приложению необходимо переключаться между иммерсивным режимом и обычным режимом. Поведение вырезания по умолчанию может привести к тому, что контент вашего приложения будет отображаться в области выреза, пока присутствуют системные панели, но не в иммерсивном режиме. Это приводит к перемещению контента вверх и вниз во время переходов, как показано в следующем примере.

    Изображение, демонстрирующее перемещение контента вверх и вниз во время переходов.
    Рисунок 8. Пример перемещения контента вверх и вниз во время переходов.

  • В иммерсивном режиме будьте осторожны при использовании оконных и экранных координат, поскольку ваше приложение не использует весь экран при отображении с черными полосами сверху и снизу. Из-за черных полос координаты относительно начала координат экрана не совпадают с координатами относительно начала координат окна. При необходимости вы можете преобразовать экранные координаты в координаты представления, используя getLocationOnScreen() . На следующем изображении показано, как различаются координаты при отображении контента с черными полосами сверху и снизу:

    Изображение, показывающее соотношение оконных и экранных координат при отображении контента в формате Letterbox.
    Рисунок 9. Координаты окна и экрана при отображении контента в формате Letterbox.

  • При обработке MotionEvent используйте MotionEvent.getX() и MotionEvent.getY() , чтобы избежать подобных проблем с координатами. Не используйте MotionEvent.getRawX() или MotionEvent.getRawY() .

Проверьте, как отображается ваш контент.

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

  1. Включите параметры разработчика .
  2. На экране «Параметры разработчика» прокрутите вниз до раздела «Рисование» и выберите «Имитировать дисплей с вырезом» .

  3. Выберите тип выреза.

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

Дополнительные ресурсы