Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

UI mit der Systemstatusleiste abstimmen

Bis Wear OS 7 (API 37) hat die Plattform keine Systemstatusleiste über Anwendungsfenstern gerendert. Apps hatten den gesamten Bildschirm zur Verfügung und konnten beliebige Inhalte oben (12 Uhr) anzeigen, z. B. eine In-App-Uhr (TimeText), benutzerdefinierte gebogene Header oder Steuerelemente oben.

Ab Wear OS 8 – und jetzt schon zum Testen in der Vorabversion im Wear OS 7.1 Beta Preview Emulator (API 37.2-beta1) verfügbar – rendert das System eine Statusleiste über den Anwendungsfenstern an der 12-Uhr-Position, um die Uhrzeit und Statusanzeigen anzuzeigen. Damit es nicht zu Überschneidungen mit der Systemstatusleiste kommt, sollten Apps keine eigene Uhr (TimeText) mehr rendern und die oberen Statusleisten-Fenstereinsätze berücksichtigen (wird ab Wear Compose 1.8 automatisch von AppScaffold und ScreenScaffold übernommen) oder die Systemstatusleiste ausblenden, wenn ein Vollbildmodus erforderlich ist.

**Abbildung 1.** Systemstatusleiste in Wear OS 8.

Die wichtigsten Vorteile sind unter anderem folgende:

Visuelle Konsistenz: Einheitliche Typografie, Platzierung und Hintergrundplatte für die Uhr im gesamten System und in allen Apps.
Systemstatusanzeigen: Ermöglicht der Plattform, Statussymbole (z. B. Anzeigen für aktives Mikrofon und Standort, Verbindungsstatus oder Akkuinformationen) und die Uhrzeit auf verschiedenen Oberflächen anzuzeigen. Es wird jeweils nur ein Symbol angezeigt, je nach Priorität.
Automatische Scroll- und Übergangskoordination: In Kombination mit Jetpack Compose für Wear OS 1.8 wird die Systemstatusleiste automatisch ausgeblendet, wenn Nutzer durch Inhalte scrollen, und nach einer kurzen Verzögerung (2 Sekunden) wieder eingeblendet.

App einrichten

Führen Sie zuerst die folgenden Schritte aus:

Installieren Sie die Android Studio-Vorabversion (Canary).
Lade im SDK-Manager das Wear OS 7.1-Vorschau-Emulator-System-Image (API 37.2-beta1) herunter. Diese Version bietet Vorabzugriff auf die Wear OS 8-Systemstatusleiste vor dem Wear OS 8 SDK.
Erstelle im Gerätemanager ein virtuelles Wear OS-Gerät mit dem Image API 37.2-beta1 und starte es.

Wenn du die Systemstatusleiste in deiner App unterstützen möchtest, aktualisiere die targetSdk-Version deiner App auf 35 oder höher. Die Plattform aktiviert die Systemstatusleiste nur für Apps, die auf API 35 oder höher ausgerichtet sind, um die Abwärtskompatibilität für ältere Apps zu gewährleisten. Aktualisieren Sie außerdem Ihre Wear Compose-Abhängigkeiten auf die neueste Alphaversion (derzeit 1.8.0-alpha02), wie im folgenden Code-Snippet gezeigt. Wenn Ihre App eine ältere Version von Wear Compose verwendet, können Sie die Migration mit dem Wear Compose Material 3-Migrationsskill vereinfachen.

android {
    defaultConfig {
        targetSdk = 35
    }
}

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

Systemstatusleiste verwenden

In der neuesten Alphaversion von Wear Compose Material 3 1.8.0 (derzeit 1.8.0-alpha02) wird Ihre App automatisch aktiviert, indem die com.google.wear.ENABLE_GLOBAL_STATUS_BAR-Property <meta-data> in Ihre AndroidManifest.xml zusammengeführt wird. Zur Laufzeit prüfen AppScaffold und ScreenScaffold, ob die Systemstatusleiste auf dem Gerät aktiviert ist und ob dieses Manifest-Opt-in-Attribut auf true gesetzt ist:

Im Vorschau-Emulator / Wear OS 8+ (wenn aktiviert): AppScaffold unterdrückt die interne TimeText, sodass die Systemstatusleiste sauber an der 12-Uhr-Position ohne Duplizierung gerendert wird. ScreenScaffold berechnet contentPadding neu, um die Begrenzungen des Statusleisten-Insets zu berücksichtigen, und koordiniert das Aus- und Einblenden der Statusleiste beim Scrollen der Liste.
Auf Geräten mit Wear OS 7 und älteren Versionen (oder wenn die Funktion nicht aktiviert ist): AppScaffold wird automatisch auf das Rendern der Standard-TimeText in der App zurückgegriffen, wobei die vollständige Abwärtskompatibilität über eine einzige Codebasis beibehalten wird.

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

Das passiert, wenn Sie das Beispiel ausführen:

Inaktiv (oben in der Liste): Die Systemstatusleiste wird auf der 12-Uhr-Position angezeigt. Der Header „Hello Status Bar“ befindet sich unter dem Bereich der Statusleiste, ohne abgeschnitten zu werden oder sich mit anderen Elementen zu überschneiden.
Nach unten scrollen: Wenn du durch die Listenelemente scrollst, wird die Statusleiste ausgeblendet und die Listenelemente werden randlos hinter dem oberen Rahmen gescrollt.
Inaktiv: Wenn du aufhörst zu scrollen und den Bildschirm loslässt, wird die Statusleiste nach etwa 2 Sekunden automatisch wieder eingeblendet.

Gängige Szenarien und Anpassungen handhaben

In den folgenden Abschnitten wird beschrieben, wie Sie mit häufigen Szenarien umgehen, die bei der Arbeit mit der Systemstatusleiste auftreten können.

Nicht scrollbare (statische) Bildschirme verarbeiten

Wende auf Bildschirmen, die ein statisches Layout (z. B. Column oder Box) anstelle einer scrollbaren Liste verwenden, das von ScreenScaffold bereitgestellte contentPadding auf dein Stammlayout an, damit die oberen UI-Elemente nicht die Statusleiste des Systems überlappen:

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

Mit interaktiven Vollbildkomponenten arbeiten

Bei interaktiven Vollbildkomponenten in Wear Compose Material 3, einschließlich AlertDialog, Dialog, Stepper, TimePicker und DatePicker, wird die Systemstatusleiste automatisch ausgeblendet, während sie auf dem Bildschirm angezeigt werden. So haben ihre Steuerelemente vollen Zugriff auf den oberen Bereich des runden Displays. Wenn sie geschlossen wird, wird die Systemstatusleiste automatisch über die WindowInsetsController-API wiederhergestellt.

In den immersiven Modus wechseln

Wenn du in den immersiven Modus wechseln möchtest, in dem sowohl die Systemstatusleiste als auch die lokale TimeText ausgeblendet werden, füge deiner App oder deinem Bildschirm das Compose-Element StatusBarSuppression hinzu. Reserviere den immersiven Modus für Bildschirme, die der Nutzer nur kurz sieht (Bestätigungs-Overlays, Dialogfelder), oder für Bildschirme, die das gesamte Display nutzen (Fortschrittsanzeigen im Vollbildmodus).

Überlegen, wann der immersive Modus auf Bildschirmebene verwendet werden sollte

Wenn nur ein bestimmter Bildschirm in deiner App im Vollbildmodus oder immersiv angezeigt werden soll, rufe StatusBarSuppression() im Inhalt von ScreenScaffold auf. ScreenScaffold unterdrückt automatisch die Systemstatusleiste (und lässt den oberen Abstand der Statusleiste weg), während dieser Bildschirm aktiv ist. Wenn du zu anderen Bildschirmen zurückkehrst, wird die Systemstatusleiste wiederhergestellt:

AppScaffold {
    ScreenScaffold() {
        StatusBarSuppression()
        // Full-screen immersive content
    }
}

Wann sollte der immersive Modus auf App-Ebene verwendet werden?

Wenn deine gesamte Anwendung (oder Activity) auf allen Bildschirmen eine immersive Vollbildoberfläche ist, verwende StatusBarSuppression auf der Ebene AppScaffold und umschließe deine Inhalte, um die Systemstatusleiste auf allen Bildschirmen zu unterdrücken:

// Use StatusBarSuppression at AppScaffold level and wrap your content
// to suppress status bar in the entire scaffold.
AppScaffold {
    StatusBarSuppression {
        SwipeDismissableNavHost(...) {
            // Nested screens inherit suppression and 0.dp padding
        }
    }
}

Benutzerdefinierte Textüberschreibungen für die Zeit anzeigen

Wenn du während der Migration für Wear OS 8 eine benutzerdefinierte gebogene Kopfzeile anzeigen oder die Systemstatusleiste auf einem bestimmten Bildschirm oder in deiner gesamten App vorübergehend deaktivieren möchtest, kannst du die Systemstatusleiste durch Übergabe einer benutzerdefinierten timeText-Komposition unterdrücken:

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

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

Mit Ansichten implementieren (nicht empfohlen)

Wenn deine App Android-Ansichten anstelle von Jetpack Compose für Wear OS verwendet, aktiviere die Funktion mit AndroidManifest.xml. Im Gegensatz zur neuesten Alpha-Version von Wear Compose Material 3, bei der die Systemstatusleiste automatisch aktiviert wird, müssen ansichtsbasierte Apps explizit aktiviert werden. Dazu muss das Tag ENABLE_GLOBAL_STATUS_BAR <meta-data> in <application> hinzugefügt werden:

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

Oberen Fenster-Inset überwachen

Verwenden Sie ViewCompat.setOnApplyWindowInsetsListener und prüfen Sie den Wert von windowInsets.getInsets(WindowInsetsCompat.Type.statusBars()). Wenn statusBarInsets.top > 0, entferne die alte 12-Uhr-UI und passe den oberen Abstand an. Andernfalls verwende die alte UI:

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
}

Statusleiste programmatisch aus- und einblenden

Im Gegensatz zu ScreenScaffold in Compose müssen ansichtsbasierte Apps die Systemstatusleiste explizit ausblenden oder einblenden (z. B. beim Aufrufen einer immersiven Vollbildansicht oder beim Koordinieren des Scrollverhaltens) und dazu WindowInsetsControllerCompat verwenden:

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())

App testen

Prüfe beim Testen deiner App im Wear OS 7.1 Beta Preview Emulator (API 37.2-beta1) Folgendes:

Uhr wird nur einmal angezeigt: Prüfe, ob nur die Uhrzeit der Systemstatusleiste auf der 12-Uhr-Position angezeigt wird und keine älteren In-App-TimeText und App-Inhalte sie überlappen.
Oberer Abstand: Prüfe, ob Bildschirmtitel, Header und obere Schaltflächen unter der Statusleiste angezeigt werden.
Vollbild-Overlays und ‑Dialogfelder: Prüfe, ob Dialogfelder, Auswahlfelder, Stepper und benutzerdefinierte Vollbildaktivitäten die Statusleiste beim Öffnen ausblenden und beim Schließen wieder einblenden.