Согласуйте интерфейс со строкой состояния системы

До Wear OS 7 (API 37) платформа не показывала системную строку состояния поверх окон приложений. Приложения занимали весь экран и могли отображать любой контент в верхней части (на 12 часов), например часы TimeText, собственные изогнутые заголовки или элементы управления.

Начиная с Wear OS 8 (и уже сейчас в предварительной версии Wear OS 7.1 Beta Preview Emulator, API 37.2-beta1) система показывает строку состояния поверх окон приложений в положении "12 часов". В ней отображаются время и индикаторы состояния. Чтобы избежать наложения на системную строку состояния, приложения не должны показывать собственные часы (TimeText) и должны учитывать верхние отступы окна строки состояния (автоматически обрабатываются AppScaffold и ScreenScaffold в Wear Compose 1.8 и более поздних версиях) или скрывать системную строку состояния, когда требуется полноэкранный режим.

Системная строка состояния в Wear OS 8
Рисунок 1. Строка состояния в Wear OS 8.

Вот основные преимущества таких кампаний:

  • Визуальное единообразие. Единый шрифт, расположение и подложка часов в системе и всех приложениях.
  • Индикаторы состояния системы. Позволяет платформе показывать значки состояния (например, индикаторы активного микрофона и местоположения, статус подключения или информацию о батарее) и время на разных поверхностях. Одновременно показывается только один значок в зависимости от приоритета.
  • Автоматическая прокрутка и координация переходов. При использовании Jetpack Compose для Wear OS 1.8 строка состояния системы автоматически скрывается, когда пользователи прокручивают контент, и снова появляется после короткой (2 секунды) задержки в режиме ожидания.

Как настроить приложение

Чтобы начать работу, выполните следующие действия:

  1. Установите Android Studio Preview (Canary).
  2. В SDK Manager скачайте системный образ эмулятора предварительной версии Wear OS 7.1 (API 37.2-beta1). Эта версия предоставляет ранний доступ к строке состояния системы Wear OS 8 до выпуска Wear OS 8 SDK.
  3. В Диспетчере устройств создайте и запустите виртуальное устройство Wear OS, используя образ API 37.2-beta1.

Чтобы в вашем приложении поддерживалась системная строка состояния, обновите версию targetSdk до 35 или выше. Платформа активирует системную строку состояния только для приложений, предназначенных для API 35 и более поздних версий, чтобы сохранить обратную совместимость с устаревшими приложениями. Кроме того, обновите зависимости Wear Compose до последней альфа-версии (сейчас это 1.8.0-alpha03), как показано в следующем фрагменте кода. Если в вашем приложении используется более старая версия Wear Compose, вы можете использовать навык миграции Wear Compose Material 3, чтобы упростить миграцию.

android {
    defaultConfig {
        targetSdk = 35
    }
}

dependencies {
    implementation("androidx.wear.compose:compose-foundation:1.8.0-alpha03")
    implementation("androidx.wear.compose:compose-material3:1.8.0-alpha03")
}

Использовать системную строку состояния

В последней альфа-версии Wear Compose Material 3 1.8.0 (сейчас это 1.8.0-alpha03) библиотека автоматически включает поддержку динамических цветов, добавляя свойство com.google.wear.ENABLE_GLOBAL_STATUS_BAR <meta-data> в файл AndroidManifest.xml. Во время выполнения AppScaffold и ScreenScaffold проверяют, включена ли на устройстве строка состояния и задано ли для свойства манифеста значение true.

  • В эмуляторе предварительной версии и Wear OS 8+ (если включено): AppScaffold подавляет внутренний TimeText, чтобы системная строка состояния отображалась в положении "12 часов" без дублирования. ScreenScaffold пересчитывает contentPadding, чтобы учесть границы вставки строки состояния, и координирует скрытие и отображение строки состояния при прокрутке списка.
  • На устройствах с Wear OS 7 и более ранними версиями (или если вы не включили эту функцию) AppScaffold автоматически возвращается к стандартному рендерингу TimeText в приложении, сохраняя полную обратную совместимость с единой базой кода.

@Composable
fun GsbSampleApp() {
    // AppScaffold coordinates the system status bar across the app
    // and falls back to rendering TimeText on Wear OS 7 and earlier.
    AppScaffold {
        val columnState = rememberTransformingLazyColumnState()

        // ScreenScaffold includes status bar top inset clearance in
        // contentPadding and hides/shows the status bar during list scrolling.
        ScreenScaffold(scrollState = columnState) { contentPadding ->
            TransformingLazyColumn(
                state = columnState,
                contentPadding = contentPadding,
            ) {
                item {
                    ListHeader { Text("Hello Status Bar") }
                }
                items(count = 15) { index ->
                    Button(onClick = { /* Handle click */ }) {
                        Text("Item #${index + 1}")
                    }
                }
            }
        }
    }
}

Вот что произойдет при запуске примера:

  • В покое (вверху списка). Строка состояния системы отображается в положении "12 часов". Заголовок Hello Status Bar находится под областью строки состояния, не перекрывая ее и не обрезаясь.
  • Прокрутка вниз. При прокрутке элементов списка строка состояния скрывается, а элементы списка прокручиваются от края до края за верхней рамкой.
  • Бездействие. Если вы прекратите прокрутку и отпустите экран, строка состояния автоматически появится снова примерно через две секунды.

Как работать с распространенными сценариями и настройками

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

Как обрабатывать статические экраны без прокрутки

На экранах со статическим макетом (например, Column или Box), а не прокручиваемым списком, примените contentPadding, предоставляемый ScreenScaffold, к корневому макету, чтобы верхние элементы интерфейса не перекрывали строку состояния системы:

AppScaffold {
    ScreenScaffold { contentPadding ->
        Column(modifier = Modifier.padding(contentPadding)) {
            Text("Static Screen Content")
        }
    }
}

Как работать с полноэкранными интерактивными компонентами

Полноэкранные интерактивные компоненты в Wear Compose Material 3, включая AlertDialog, Dialog, Stepper, TimePicker и DatePicker, автоматически скрывают системную строку состояния, чтобы элементы управления могли занимать всю верхнюю часть круглого экрана. Когда окно закрывается, строка состояния автоматически восстанавливается с помощью API WindowInsetsController.

Переключиться в режим погружения

Чтобы переключиться в режим погружения, в котором скрыты и строка состояния системы, и локальная панель TimeText, примените модификатор Modifier.suppressStatusBar к приложению, экрану или компоненту. Режим погружения лучше использовать для экранов, которые пользователь видит недолго (например, оверлеи подтверждения, диалоговые окна), или для тех, которые занимают весь экран (например, полноэкранные индикаторы выполнения).

Когда использовать режим погружения на уровне экрана

Если полноэкранным или иммерсивным должен быть только определенный экран в приложении, примените Modifier.suppressStatusBar к ScreenScaffold. Пока этот экран активен, ScreenScaffold автоматически скрывает системную строку состояния и уменьшает верхний отступ до 0.dp. При переходе на другие экраны ScreenScaffold восстанавливает системную строку состояния.

AppScaffold {
    ScreenScaffold(modifier = Modifier.suppressStatusBar()) { contentPadding ->
        Box(modifier = Modifier.fillMaxSize().padding(contentPadding)) {
            // Full-screen immersive content
        }
    }
}

Чтобы скрыть строку состояния системы, когда на экране находится отдельный компонент, примените Modifier.suppressStatusBar непосредственно к этому компоненту. Этот модификатор полезно применять к полноэкранным компонентам, таким как полноэкранные индикаторы выполнения и настраиваемые диалоговые окна.

Когда использовать режим погружения на уровне приложения

Если ваше приложение работает в полноэкранном режиме, примените Modifier.suppressStatusBar к AppScaffold, чтобы скрыть строку состояния на всех экранах:

// Apply Modifier.suppressStatusBar() to AppScaffold to suppress the status bar
// and collapse insets across all child screens.
AppScaffold(modifier = Modifier.suppressStatusBar()) {
    SwipeDismissableNavHost(
        navController = navController,
        startDestination = "home",
    ) {
        // Nested screens inherit suppression and 0.dp padding
    }
}

Как настроить замену текста для времени

Если вам нужно показать собственный изогнутый заголовок или временно отключить системную строку состояния на определенном экране или во всем приложении во время перехода на Wear OS 8, передайте собственную composable-функцию timeText, чтобы скрыть системную строку состояния:

// Screen-level custom TimeText override:
ScreenScaffold(
    timeText = { TimeText { timeTextCurvedText("Custom Status") } },
) {
    // Content
}

// App-level opt-out using in-app TimeText:
AppScaffold(
    timeText = { TimeText() },
) {
    // Screens
}

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

Если в вашем приложении используются представления Android, а не Jetpack Compose для Wear OS, включите эту функцию с помощью AndroidManifest.xml. В отличие от последней альфа-версии Wear Compose Material 3, в которой системная строка состояния включается автоматически, в приложениях на основе View ее нужно включить явным образом, добавив тег ENABLE_GLOBAL_STATUS_BAR <meta-data> в <application>:

<meta-data
    android:name="com.google.wear.ENABLE_GLOBAL_STATUS_BAR"
    android:value="true" />

Отслеживание вставок верхнего окна

Используйте ViewCompat.setOnApplyWindowInsetsListener и проверьте значение windowInsets.getInsets(WindowInsetsCompat.Type.statusBars()). Если statusBarInsets.top > 0, удалите устаревший интерфейс на 12 часов и настройте верхний отступ. В противном случае вернитесь к устаревшему интерфейсу.

ViewCompat.setOnApplyWindowInsetsListener(rootView) { view, windowInsets ->
    val statusBarInsets = windowInsets.getInsets(
        WindowInsetsCompat.Type.statusBars()
    )

    if (statusBarInsets.top > 0) {
        // status bar is visible: remove legacy 12 o'clock UI and apply top inset padding
        view.updatePadding(top = statusBarInsets.top)
    } else {
        // status bar is not visible: fall back to legacy UI and padding
    }

    WindowInsetsCompat.CONSUMED
}

Как программно скрыть и показать строку состояния

В отличие от ScreenScaffold в Compose, в приложениях на основе View необходимо явно скрывать или показывать системную строку состояния (например, при переходе в полноэкранный режим или при прокрутке) с помощью WindowInsetsControllerCompat:

val insetsController = WindowCompat.getInsetsController(window, window.decorView)

// Hide the status bar
insetsController.hide(WindowInsetsCompat.Type.statusBars())

// Show the status bar
insetsController.show(WindowInsetsCompat.Type.statusBars())

Тестирование приложения

При тестировании приложения в эмуляторе предварительной бета-версии Wear OS 7.1 (API 37.2-beta1) проверьте следующее:

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