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

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

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

Рисунок 1. Отображение от края до края, чтобы рисовать за системными строками.

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

В Android 15 (уровень API 35) и более поздних версиях контент приложения, использующего SDK 35, отображается под системными строками и вырезами на экране. Это позволяет сделать приложение более удобным и использовать все доступное пространство окна.

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

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

Основные сведения о вставках

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

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

Each portion of the system UI has a corresponding type of inset that describes its size and where it is placed. Например, вставки строки состояния предоставляют размер и положение строки состояния, а вставки панели навигации предоставляют размер и положение панели навигации. Каждый тип вставки состоит из четырех размеров в пикселях: сверху, слева, справа и снизу. Эти размеры определяют, насколько системный интерфейс выходит за пределы соответствующих сторон окна приложения. Чтобы избежать перекрытия с этим типом системного пользовательского интерфейса, пользовательский интерфейс приложения должен быть вставлен на эту величину.

В WindowInsets доступны следующие встроенные типы вставок Android:

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, чтобы контент не перекрывался визуально и не мешал жестам.