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

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

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

Рисунок 1. Прорисовка области за системными панелями от края до края.

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

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

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

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

Вставка основных принципов

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

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

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

Эти встроенные типы вставок 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	Вставки, представляющие количество вставок, в которых система будет перехватывать жесты для навигации. Приложения могут вручную указать обработку ограниченного количества этих жестов с помощью 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 , чтобы гарантировать отсутствие визуального перекрытия содержимого и перекрытия жестов.

{% дословно %} {% endverbatim %}