easydev991/jetpack-compose-safe-areas

Безопасные зоны в Jetpack Compose (Jetpack-WorkoutApp)

When to Use

• Используй этот навык, когда работаешь с Scaffold и TopAppBar в Compose в Jetpack-WorkoutApp
• Используй этот навык, когда создаешь новые экраны с верхним баром или без него
• Используй этот навык, когда контент перекрывается TopAppBar или BottomBar
• Используй этот навык, когда нужно обеспечить корректное отображение на устройствах с вырезом экрана (notch)
• Используй этот навык, когда контент заезжает под статус-бар или системные элементы
• Этот навык полезен при рефакторинге существующих экранов для корректной обработки безопасных зон
• Этот навык помогает избежать распространённых ошибок при работе с windowInsets

Основной принцип

В Jetpack Compose компонент TopAppBar автоматически обрабатывает безопасные зоны (status bar insets) и не требует дополнительной настройки. Это означает, что при правильной реализации заголовок экрана не будет перекрываться камерой, динамиком или другими системными элементами на устройствах с вырезом экрана.

Ключевое правило: НИКОГДА не используй windowInsets = WindowInsets(top = 0) в TopAppBar. Это отключает автоматическую обработку безопасных зон и приводит к перекрытию контента.

Архитектура безопасных зон

MainActivity

В MainActivity используется enableEdgeToEdge(), который заставляет приложение занимать весь экран, включая области под системными барами. Это требует специальной настройки insets на уровне Scaffold.

Корневой Scaffold (RootScreen)

В корневом экране приложения (RootScreen) используется Scaffold с BottomNavigationBar. Важно отключить автоматические отступы для контента через contentWindowInsets = WindowInsets(0, 0, 0, 0), чтобы контент не получал лишних отступов. Параметр paddingValues используется только для учёта BottomNavigationBar.

Правила:

• В корневом Scaffold всегда отключай автоматические отступы для контента через contentWindowInsets = WindowInsets(0, 0, 0, 0)
• Параметр paddingValues применяется только к NavHost для учёта BottomNavigationBar
• На отдельных экранах безопасная зона обрабатывается отдельно через TopAppBar или вручную

Экраны с TopAppBar

Когда экран имеет TopAppBar, безопасная зона обрабатывается автоматически. TopAppBar сам определяет высоту статус-бара и добавляет необходимые отступы.

Правила:

• Не указывай параметр windowInsets в TopAppBar
• Для LazyColumn применяй весь paddingValues через модификатор компонента, а не через contentPadding
• Для Column используй fillMaxWidth() вместо fillMaxSize() для правильной работы безопасных зон
• Всегда применяй paddingValues к контенту, чтобы контент не перекрывался TopAppBar или BottomBar

Экраны без TopAppBar

Если экран не имеет TopAppBar, необходимо вручную добавить безопасную зону сверху, чтобы контент не заезжал под статус-бар. Для этого используется WindowInsets.systemBars.top.

Правила:

• Добавляй WindowInsets.systemBars.top как отдельный padding
• Используй paddingValues только для BottomNavigationBar (если он есть)
• Применяй safe zone до применения paddingValues

Примечание: В текущей реализации проекта все экраны используют TopAppBar, поэтому этот сценарий пока не применяется.

Импорты

Для работы с безопасными зонами необходимы следующие импорты:

• androidx.compose.foundation.layout.WindowInsets - для работы с системными вставками
• androidx.compose.foundation.layout.padding - для применения отступов
• androidx.compose.foundation.layout.systemBars - для доступа к статус-бару и навигационной панели
• androidx.compose.ui.res.dimensionResource - для получения размеров из ресурсов

Типичные ошибки

Ошибка 1: Использование fillMaxSize() вместо fillMaxWidth() для Column

Проблема: При использовании fillMaxSize() вместо fillMaxWidth() для Column при повороте экрана контент наезжает на камеру или динамик.

Решение: Используй fillMaxWidth() вместо fillMaxSize() для Column с вертикальной прокруткой.

Ошибка 2: Использование contentPadding для LazyColumn с calculateTopPadding()

Проблема: При использовании calculateTopPadding() в contentPadding LazyColumn контент заезжает на камеру при повороте экрана.

Решение: Применяй весь paddingValues через модификатор LazyColumn, а contentPadding используй только для горизонтальных отступов и небольшого визуального отступа сверху.

Проверка корректности

Критерии правильной реализации

При реализации безопасных зон проверяй следующие критерии:

• ✅ TopAppBar НЕ имеет параметр windowInsets = WindowInsets(top = 0)
• ✅ RootScreen имеет contentWindowInsets = WindowInsets(0, 0, 0, 0)
• ✅ Экраны с TopAppBar + LazyColumn используют Modifier.padding(paddingValues) для LazyColumn
• ✅ Экраны с TopAppBar + Column используют fillMaxWidth() и Modifier.padding(paddingValues)
• ✅ Экраны без TopAppBar добавляют WindowInsets.systemBars.top вручную

Тестирование на устройстве с вырезом экрана

Для полной проверки корректности обработки безопасных зон:

1. Открой приложение на устройстве с вырезом экрана (notch, динамик или камера)
2. Проверь что заголовок TopAppBar не заезжает под камеру или динамик
3. Проверь что контент не перекрывается TopAppBar (прокрути список до верха)
4. Проверь что контент не перекрывается BottomBar (прокрути список до низа)
5. Поверни экран на 90 градусов и проверь что контент не заезжает на камеру/динамик
6. Поверни экран на 270 градусов и проверь что контент не заезжает на камеру/динамик
7. Проверь что на экранах без TopAppBar контент не заезжает под статус-бар
8. Протестируй в портретной и альбомной ориентации

Ссылки на примеры

Более подробные примеры кода см. в файле references/EXAMPLES.md.

Доступные примеры

• Корневой Scaffold (RootScreen) - пример настройки корневого экрана
• Экраны с TopAppBar - правильный и неправильный подходы
• Экраны без TopAppBar - пример ручного добавления безопасной зоны
• Pattern 1: Экран с TopAppBar + LazyColumn - пример для списков с использованием dimensionResource
• Pattern 2: Экран с TopAppBar + Column - пример для статического контента
• Pattern 3: Экран с TopAppBar + View без прокрутки - пример для простых компонентов
• Ошибка 1: Использование fillMaxSize() вместо fillMaxWidth() - сравнение правильного и неправильного подхода
• Ошибка 2: Использование contentPadding для LazyColumn - сравнение правильного и неправильного подхода
• Ошибка 3: Добавление windowInsets в TopAppBar - сравнение правильного и неправильного подхода
• Ошибка 4: Игнорирование paddingValues в контенте - сравнение правильного и неправильного подхода
• Ошибка 5: Отсутствие безопасной зоны на экранах без TopAppBar - сравнение правильного и неправильного подхода
• Реализованные экраны - примеры из проекта:
  • ParksRootScreen - LazyColumn
  • EventsScreen - LazyColumn
  • MoreScreen - Column
  • ThemeIconScreen - Column
• Полный пример экрана с TopAppBar - готовый код экрана мероприятий
• Полный пример экрана без TopAppBar - готовый код приветственного экрана

Референсы

Jetpack Compose documentation: https://developer.android.com/jetpack/compose/layouts/insets