Mengoordinasikan UI Anda dengan status bar sistem

Catatan: Status bar sistem tersedia untuk pengujian eksperimental di Emulator Pratinjau Beta Wear OS 7.1 (API 37.2-beta1). Fitur ini akan tersedia di perangkat fisik selama rilis Wear OS mendatang yang menjalankan Wear OS 8.

Hingga Wear OS 7 (API 37), platform tidak merender status bar sistem di atas jendela aplikasi—aplikasi memiliki seluruh layar dan dapat menggambar konten apa pun di posisi atas (pukul 12) (seperti jam TimeText dalam aplikasi, header melengkung kustom, atau kontrol atas).

Mulai Wear OS 8—dan kini tersedia untuk pengujian pratinjau awal di Emulator Pratinjau Beta Wear OS 7.1 (API 37.2-beta1)—sistem merender status bar di atas jendela aplikasi pada posisi jam 12 untuk menampilkan indikator waktu dan status. Untuk mencegah tumpang-tindih dengan status bar sistem, aplikasi harus berhenti merender jamnya sendiri (TimeText) dan mengikuti inset jendela status bar atas (ditangani secara otomatis oleh AppScaffold dan ScreenScaffold dari Wear Compose 1.8 dan yang lebih baru), atau menyembunyikan status bar sistem saat pengalaman imersif layar penuh diperlukan.

Gambar 1. Status bar sistem di Wear OS 8.

Manfaat utamanya meliputi:

• Konsistensi visual: tipografi, penempatan, dan pelat belakang jam yang seragam di seluruh sistem dan semua aplikasi.
• Indikator status sistem: memungkinkan platform menampilkan ikon status (seperti indikator mikrofon dan lokasi aktif, status konektivitas, atau informasi baterai) dan waktu di seluruh platform. Hanya satu ikon yang ditampilkan dalam satu waktu, berdasarkan prioritas.
• Koordinasi scroll & transisi otomatis: jika dipasangkan dengan Jetpack Compose untuk Wear OS 1.8, status bar sistem akan otomatis disembunyikan saat pengguna men-scroll konten dan muncul kembali setelah jeda tidak ada aktivitas singkat (2 dtk).

Menyiapkan aplikasi

Untuk memulai, selesaikan langkah-langkah prasyarat berikut:

1. Instal Pratinjau Android Studio (Canary).
2. Di SDK Manager, download Image Sistem Emulator Pratinjau Wear OS 7.1 (API 37.2-beta1). Versi ini memberikan akses awal ke status bar sistem Wear OS 8 sebelum SDK Wear OS 8.
3. Di Device Manager, buat dan luncurkan perangkat virtual Wear OS menggunakan image API 37.2-beta1.

Untuk mendukung status bar sistem di aplikasi Anda, update versi targetSdk aplikasi Anda ke 35 atau yang lebih tinggi. Platform hanya mengaktifkan status bar sistem untuk aplikasi yang menargetkan API 35+ guna mempertahankan kompatibilitas mundur untuk aplikasi lama. Selain itu, update dependensi Wear Compose ke versi alfa terbaru—saat ini 1.8.0-alpha03—seperti yang ditunjukkan dalam cuplikan kode berikut. Jika aplikasi Anda menggunakan Wear Compose versi lama, Anda dapat menggunakan kemampuan migrasi Wear Compose Material 3 untuk memfasilitasi migrasi.

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")
}

Menggunakan status bar sistem

Catatan: Versi Compose untuk Wear OS yang digunakan dalam cuplikan berikut adalah rilis alfa. Platform API yang tepat dapat berubah sewaktu-waktu.

Dalam versi alfa terbaru Wear Compose Material 3 1.8.0—saat ini 1.8.0-alpha03—library akan otomatis mengaktifkan aplikasi Anda dengan menggabungkan properti com.google.wear.ENABLE_GLOBAL_STATUS_BAR <meta-data> ke dalam AndroidManifest.xml. Pada runtime, AppScaffold dan ScreenScaffold memeriksa apakah status bar sistem diaktifkan di perangkat dan apakah properti keikutsertaan manifes ini disetel ke true:

• Di emulator pratinjau/Wear OS 8+ (jika diaktifkan): AppScaffold menonaktifkan TimeText internalnya sehingga status bar sistem dirender dengan rapi di posisi jam 12 tanpa duplikasi. ScreenScaffold menghitung ulang contentPadding untuk memperhitungkan batas inset Status Bar dan mengoordinasikan penyembunyian dan penampilan status bar saat daftar di-scroll.
• Di Wear OS 7 dan perangkat yang lebih lama (atau jika tidak diaktifkan): AppScaffold akan otomatis kembali merender TimeText dalam aplikasi standar, sehingga mempertahankan kompatibilitas mundur penuh dari satu codebase.

@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}")
                    }
                }
            }
        }
    }
}
StatusBar.kt

Berikut yang akan terjadi saat menjalankan contoh:

• Saat tidak aktif (atas daftar): status bar sistem ditampilkan di posisi jam 12. Header "Hello Status Bar" berada di bawah area inset status bar tanpa terpotong atau tumpang-tindih.
• Men-scroll ke bawah: saat Anda men-scroll item daftar, status bar akan disembunyikan, dan item daftar akan di-scroll dari tepi ke tepi di belakang bezel atas.
• Tidak ada aktivitas: saat Anda berhenti men-scroll dan melepaskan layar, status bar akan otomatis muncul kembali setelah sekitar 2 detik.

Menangani skenario dan penyesuaian umum

Bagian berikut menjelaskan cara menangani skenario umum yang mungkin Anda alami saat menggunakan status bar sistem.

Menangani layar yang tidak dapat di-scroll (statis)

Di layar yang menggunakan tata letak statis (seperti Column atau Box), bukan daftar scroll, terapkan contentPadding yang disediakan oleh ScreenScaffold ke tata letak root agar elemen UI teratas tidak tumpang-tindih dengan status bar sistem:

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

Menggunakan komponen interaktif layar penuh

Komponen interaktif layar penuh di Wear Compose Material 3—termasuk AlertDialog, Dialog, Stepper, TimePicker, dan DatePicker—secara otomatis menyembunyikan status bar sistem saat berada di layar sehingga kontrolnya memiliki akses penuh ke bagian atas layar melingkar. Saat ditutup, status bar sistem akan otomatis dipulihkan menggunakan API pengontrol inset jendela.

Beralih ke mode imersif

Untuk beralih ke mode imersif—tempat status bar sistem dan TimeText lokal disembunyikan—terapkan pengubah Modifier.suppressStatusBar ke aplikasi, layar, atau komponen Anda. Gunakan mode imersif untuk layar yang dilihat pengguna sebentar (overlay konfirmasi, dialog) atau yang menggunakan seluruh layar (indikator progres layar penuh).

Mempertimbangkan kapan harus menggunakan mode imersif tingkat layar

Jika hanya layar tertentu di aplikasi Anda yang harus dalam mode layar penuh atau imersif, terapkan Modifier.suppressStatusBar ke ScreenScaffold. Saat layar tersebut aktif, ScreenScaffold akan otomatis menyembunyikan status bar sistem dan menciutkan padding inset status bar atas menjadi 0.dp. Saat Anda kembali ke layar lain, ScreenScaffold akan memulihkan status bar sistem:

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

Untuk menyembunyikan status bar sistem saat komponen tertentu ditampilkan di layar, terapkan Modifier.suppressStatusBar langsung ke komponen tersebut. Pengubah ini berguna untuk diterapkan ke komponen layar penuh, seperti indikator progres layar penuh dan jendela dialog kustom.

Mempertimbangkan kapan harus menggunakan mode imersif tingkat aplikasi

Perhatian: Mode imersif tingkat aplikasi tidak direkomendasikan untuk sebagian besar aplikasi karena pengguna akan kehilangan akses ke waktu dan indikator status penting di setiap layar.

Jika seluruh aplikasi Anda adalah pengalaman layar penuh yang imersif, terapkan Modifier.suppressStatusBar ke AppScaffold untuk menyembunyikan status bar sistem di semua layar:

// 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
    }
}
StatusBar.kt

Menampilkan penggantian teks waktu kustom

Jika Anda perlu menampilkan header melengkung kustom atau memilih tidak menggunakan status bar sistem untuk sementara di layar tertentu atau di seluruh aplikasi selama migrasi untuk Wear OS 8, meneruskan composable timeText kustom akan menyembunyikan status bar sistem:

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

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

Menerapkan menggunakan Tampilan (tidak direkomendasikan)

Perhatian: Android secara resmi mengutamakan Compose. Ikuti langkah-langkah ini hanya jika Anda benar-benar harus terus menggunakan tampilan di aplikasi. Sebaiknya Anda bermigrasi ke Compose untuk memanfaatkan fitur dan kemampuan UI Wear OS terbaru.

Jika aplikasi Anda menggunakan View Android, bukan Jetpack Compose untuk Wear OS, pilih ikut serta menggunakan AndroidManifest.xml. Tidak seperti rilis alfa terbaru Wear Compose Material 3, yang mengaktifkan status bar sistem secara otomatis, aplikasi berbasis View harus diikutsertakan secara eksplisit dengan menambahkan tag ENABLE_GLOBAL_STATUS_BAR <meta-data> di dalam <application>:

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

Memantau inset jendela atas

Gunakan ViewCompat.setOnApplyWindowInsetsListener dan periksa nilai windowInsets.getInsets(WindowInsetsCompat.Type.statusBars()). Jika statusBarInsets.top > 0, hapus UI jam 12 lama dan sesuaikan padding atas; jika tidak, kembali ke UI lama:

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
}
StatusBar.kt

Menyembunyikan dan menampilkan status bar secara terprogram

Tidak seperti ScreenScaffold di Compose, aplikasi berbasis View harus secara eksplisit menyembunyikan atau menampilkan status bar sistem (misalnya, saat memasuki tampilan imersif layar penuh atau mengoordinasikan perilaku scroll-away) menggunakan 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())
StatusBar.kt

Menguji aplikasi

Saat menguji aplikasi di Emulator Pratinjau Wear OS 7.1 Beta (API 37.2-beta1), periksa hal berikut:

• Jam hanya muncul sekali: Pastikan hanya waktu status bar sistem yang muncul di posisi jam 12 dan tidak ada TimeText dalam aplikasi lama dan konten aplikasi yang tumpang-tindih dengannya.
• Padding atas: Pastikan judul layar, header, dan tombol atas muncul di bawah status bar.
• Overlay & dialog layar penuh: Pastikan dialog, pemilih, stepper, dan aktivitas layar penuh kustom menyembunyikan status bar saat dibuka, dan memulihkannya saat ditutup.