Об оконных вставках

Платформа Android отвечает за отрисовку системного пользовательского интерфейса, такого как строка состояния и панель навигации. Этот системный интерфейс отображается независимо от того, какое приложение использует пользователь.

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

Рисунок 1. Рисование от края до края за решеткой системы.

В Android 14 (уровень API 34) и более ранних версиях пользовательский интерфейс вашего приложения по умолчанию не отображается под системными панелями и вырезами на экране.

На Android 15 (уровень API 35) и выше ваше приложение будет отображаться под системными панелями и вырезами на экране, как только приложение будет ориентировано на SDK 35. Это обеспечивает более плавный пользовательский интерфейс и позволяет вашему приложению в полной мере использовать доступное ему пространство окна.

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

Важно: поддержка отображения от края до края начинает действовать на Android 15 и выше, как только ваше приложение будет ориентировано на SDK 35. Если ваше приложение еще не поддерживает отображение от края до края, некоторые его части могут быть скрыты, и вам потребуется обработать отступы. В зависимости от приложения, эта работа может быть значительной или незначительной. Компонент Material 3 Scaffold может упростить работу по обеспечению совместимости с поддержкой отображения от края до края в Android 15. См. раздел «Создание компонента Scaffold для объединения пользовательского интерфейса» .

Основные принципы вставки

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

Размер системного пользовательского интерфейса и информация о его местоположении задаются с помощью параметров отступов (insets) .

Каждая часть системного интерфейса имеет соответствующий тип отступа, описывающий её размер и местоположение. Например, отступы для строки состояния определяют размер и положение строки состояния, а отступы для панели навигации — размер и положение панели навигации. Каждый тип отступа состоит из четырёх пиксельных измерений: сверху, слева, справа и снизу. Эти измерения определяют, насколько системный интерфейс отстоит от соответствующих сторон окна приложения. Следовательно, чтобы избежать перекрытия с этим типом системного интерфейса, интерфейс приложения должен иметь отступ на это значение.

Эти встроенные типы вставок Android доступны через WindowInsets :

WindowInsets.statusBars	Вставки с описанием строк состояния. Это верхние панели системного интерфейса, содержащие значки уведомлений и другие индикаторы.
WindowInsets.statusBarsIgnoringVisibility	Отступы строки состояния отображаются, когда она видна. Если строка состояния в данный момент скрыта (из-за перехода в полноэкранный режим), то отступы основной строки состояния будут пустыми, но эти отступы будут непустыми.
WindowInsets.navigationBars	Вставки описывают панели навигации. Это системные панели пользовательского интерфейса слева, справа или снизу устройства, описывающие панель задач или значки навигации. Они могут изменяться во время выполнения в зависимости от предпочтительного метода навигации пользователя и его взаимодействия с панелью задач.
WindowInsets.navigationBarsIgnoringVisibility	Отступы панели навигации отображаются, когда она видна. Если панели навигации в данный момент скрыты (из-за перехода в полноэкранный режим), то отступы основной панели навигации будут пустыми, но эти отступы будут непустыми.
WindowInsets.captionBar	Вставка с описанием оформления окна пользовательского интерфейса системы, если окно имеет произвольную форму, например, заголовок окна в верхней части экрана.
WindowInsets.captionBarIgnoringVisibility	Отступы в строке подписи отображаются, когда она видна. Если в данный момент строки подписи скрыты, то основные отступы в строке подписи будут пустыми, но эти отступы будут непустыми.
WindowInsets.systemBars	Объединение элементов системной панели, включающих строку состояния, панель навигации и строку подписей.
WindowInsets.systemBarsIgnoringVisibility	Отступы системной панели отображаются, когда она видна. Если системные панели в данный момент скрыты (из-за перехода в полноэкранный режим), то отступы основной системной панели будут пустыми, но эти отступы будут непустыми.
WindowInsets.ime	На вставках показано, какое пространство снизу занимает программная клавиатура.
WindowInsets.imeAnimationSource	На вставках показано, какое пространство занимала программная клавиатура до начала текущей анимации клавиатуры.
WindowInsets.imeAnimationTarget	Вставки описывают объем пространства, которое займет программная клавиатура после завершения текущей анимации клавиатуры.
WindowInsets.tappableElement	Тип вставок, описывающих более подробную информацию о пользовательском интерфейсе навигации, указывающий на пространство, где «касания» будут обрабатываться системой, а не приложением. Для прозрачных панелей навигации с управлением жестами некоторые элементы приложения могут быть доступны для касания через пользовательский интерфейс навигации системы.
WindowInsets.tappableElementIgnoringVisibility	Отступы для элементов, на которые можно нажимать, сохраняются, когда они видны. Если элементы, на которые можно нажимать, в данный момент скрыты (из-за перехода в иммерсивный полноэкранный режим), то отступы для основных элементов, на которые можно нажимать, будут пустыми, но эти отступы будут непустыми.
WindowInsets.systemGestures	Параметр "insets" определяет количество областей, в которых система будет перехватывать жесты для навигации. Приложения могут вручную указать обработку ограниченного количества таких жестов с помощью Modifier.systemGestureExclusion .
WindowInsets.mandatorySystemGestures	Подмножество системных жестов, которые всегда будут обрабатываться системой и от которых нельзя отказаться с помощью Modifier.systemGestureExclusion .
WindowInsets.displayCutout	Вставки показывают необходимое расстояние, чтобы избежать перекрытия с вырезом в дисплее (выемкой или отверстием).
WindowInsets.waterfall	На вставках показаны изогнутые участки дисплея типа «водопад». Дисплей типа «водопад» имеет изогнутые участки вдоль краев экрана, где экран начинает обтекать боковые стороны устройства.

Эти типы можно разделить на три «безопасных» типа вставок, которые гарантируют, что содержимое не будет перекрыто:

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

Эти «безопасные» типы вставок защищают контент различными способами в зависимости от используемых платформ:

• Используйте WindowInsets.safeDrawing для защиты содержимого, которое не должно отображаться под системным интерфейсом. Это наиболее распространенное использование отступов: предотвращение отображения содержимого, частично или полностью скрытого системным интерфейсом.
• Используйте WindowInsets.safeGestures для защиты контента, управляемого жестами. Это предотвратит конфликт системных жестов с жестами приложений (например, жестами для нижних панелей, каруселей или в играх).
• Используйте WindowInsets.safeContent как комбинацию WindowInsets.safeDrawing и WindowInsets.safeGestures , чтобы гарантировать отсутствие визуального и жестового наложения контента.

{% verbatim %} {% endverbatim %}