Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Coordina la UI con la barra di stato del sistema

Fino a Wear OS 7 (API 37), la piattaforma non eseguiva il rendering di una barra di stato di sistema sopra le finestre delle applicazioni: le app avevano il controllo dell'intero schermo e potevano disegnare qualsiasi contenuto nella posizione superiore (ore 12), ad esempio un orologio TimeText in-app, intestazioni curve personalizzate o controlli superiori.

A partire da Wear OS 8, e ora disponibile per i test in anteprima nell'emulatore di Wear OS 7.1 Beta Preview (API 37.2-beta1), il sistema esegue il rendering di una barra di stato sopra le finestre dell'applicazione nella posizione delle ore 12 per visualizzare gli indicatori di ora e stato. Per evitare sovrapposizioni con la barra di stato del sistema, le app devono interrompere il rendering del proprio orologio (TimeText) e rispettare gli inset della finestra della barra di stato superiore (gestiti automaticamente da AppScaffold e ScreenScaffold da Wear Compose 1.8 in poi) o nascondere la barra di stato del sistema quando è necessaria un'esperienza immersiva a schermo intero.

**Figura 1.** Barra di stato del sistema in Wear OS 8.

I vantaggi principali includono:

Coerenza visiva: tipografia, posizionamento e sfondo dell'orologio uniformi nel sistema e in tutte le app.
Indicatori di stato del sistema: consente alla piattaforma di visualizzare le icone di stato (ad esempio gli indicatori di microfono e posizione attivi, lo stato della connettività o le informazioni sulla batteria) e l'ora su tutte le piattaforme. Viene mostrata una sola icona alla volta, in base alla priorità.
Coordinamento automatico di scorrimento e transizione: se abbinata a Jetpack Compose per Wear OS 1.8, la barra di stato del sistema si nasconde automaticamente quando gli utenti scorrono i contenuti e riappare dopo un breve ritardo di inattività (2 secondi).

Configurare l'app

Per iniziare, completa i seguenti passaggi preliminari:

Installa l'anteprima di Android Studio (Canary).
In SDK Manager, scarica l'immagine di sistema dell'emulatore di Wear OS 7.1 Preview (API 37.2-beta1). Questa versione fornisce l'accesso in anteprima alla barra di stato del sistema Wear OS 8 prima dell'SDK Wear OS 8.
In Gestione dispositivi, crea e avvia un dispositivo virtuale Wear OS utilizzando l'immagine API 37.2-beta1.

Per supportare la barra di stato di sistema nella tua app, aggiorna la versione di targetSdk dell'app alla versione 35 o successive. La piattaforma attiva la barra di stato di sistema solo per le app che hanno come target l'API 35 o versioni successive per preservare la compatibilità con le versioni precedenti delle app legacy. Inoltre, aggiorna le dipendenze di Wear Compose all'ultima versione alpha, attualmente 1.8.0-alpha02, come mostrato nello snippet di codice seguente. Se la tua app utilizza una versione precedente di Wear Compose, puoi utilizzare la competenza di migrazione a Wear Compose Material 3 per facilitare la migrazione.

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

Utilizza la barra di stato del sistema

Nell'ultima versione alpha di Wear Compose Material 3 1.8.0, attualmente 1.8.0-alpha02, la libreria attiva automaticamente la tua app unendo la proprietà com.google.wear.ENABLE_GLOBAL_STATUS_BAR <meta-data> nel tuo AndroidManifest.xml. In fase di runtime, AppScaffold e ScreenScaffold controllano se la barra di stato del sistema è attivata sul dispositivo e se questa proprietà di attivazione del file manifest è impostata su true:

Sull'emulatore di anteprima/Wear OS 8 e versioni successive (se attivato): AppScaffold elimina il suo TimeText interno in modo che la barra di stato del sistema venga visualizzata correttamente nella posizione delle 12:00 senza duplicazioni. ScreenScaffold ricalcola contentPadding per tenere conto dei limiti di inset della barra di stato e coordina la visualizzazione e l'occultamento della barra di stato durante lo scorrimento dell'elenco.
Sui dispositivi Wear OS 7 e versioni precedenti (o se non hai eseguito l'attivazione): AppScaffold esegue automaticamente il rendering della TimeText standard in-app, mantenendo la piena compatibilità con le versioni precedenti da un'unica base di codice.

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

Ecco cosa aspettarsi quando esegui l'esempio:

A riposo (in cima all'elenco): la barra di stato del sistema viene visualizzata nella posizione delle ore 12. L'intestazione "Hello Status Bar" si trova sotto l'area di inserimento della barra di stato senza ritagli o sovrapposizioni.
Scorrimento verso il basso: mentre scorri gli elementi dell'elenco, la barra di stato si nasconde e gli elementi dell'elenco scorrono da un bordo all'altro dietro la cornice superiore.
Inattiva: quando interrompi lo scorrimento e rilasci lo schermo, la barra di stato ricompare automaticamente dopo circa 2 secondi.

Gestisci scenari e personalizzazioni comuni

Le sezioni seguenti descrivono come gestire gli scenari comuni che potresti incontrare quando utilizzi la barra di stato del sistema.

Gestisci le schermate non scorrevoli (statiche)

Nelle schermate che utilizzano un layout statico (ad esempio Column o Box) anziché un elenco a scorrimento, applica il contentPadding fornito da ScreenScaffold al layout principale in modo che gli elementi UI superiori non si sovrappongano alla barra di stato del sistema:

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

Utilizza i componenti interattivi a schermo intero

I componenti interattivi a schermo intero in Wear Compose Material 3, tra cui AlertDialog, Dialog, Stepper, TimePicker e DatePicker, nascondono automaticamente la barra di stato del sistema quando sono sullo schermo, in modo che i relativi controlli abbiano accesso completo alla parte superiore del display circolare. Quando viene chiusa, la barra di stato del sistema viene ripristinata automaticamente utilizzando l'API del controller degli inset della finestra.

Passa alla modalità immersiva

Per passare alla modalità immersiva, in cui sia la barra di stato del sistema sia l'elemento TimeText locale sono nascosti, aggiungi il composable StatusBarSuppression alla tua app o alla tua schermata. Riserva la modalità immersiva alle schermate che l'utente vede brevemente (overlay di conferma, finestre di dialogo) o che utilizzano l'intero display (indicatori di avanzamento a schermo intero).

Valuta quando utilizzare la modalità immersiva a livello di schermata

Se solo una schermata specifica della tua app deve essere a schermo intero/immersiva, chiama StatusBarSuppression() all'interno dei contenuti di ScreenScaffold. ScreenScaffold sopprime automaticamente la barra di stato del sistema (e omette il padding dell'inset della barra di stato superiore) mentre la schermata è attiva, quindi ripristina la barra di stato del sistema quando si torna ad altre schermate:

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

Valuta quando utilizzare la modalità immersiva a livello di app

Se l'intera applicazione (o Activity) è un'esperienza immersiva a schermo intero su tutte le schermate, utilizza StatusBarSuppression a livello di AppScaffold e aggrega i contenuti per eliminare la barra di stato del sistema in tutte le schermate:

// 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
        }
    }
}

Visualizza gli override del testo dell'ora personalizzata

Se devi visualizzare un'intestazione curva personalizzata o disattivare temporaneamente la barra di stato del sistema su una schermata specifica o nell'intera app durante la migrazione per Wear OS 8, il passaggio di un composable timeText personalizzato sopprime la barra di stato del sistema:

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

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

Implementazione tramite le visualizzazioni (non consigliata)

Se la tua app utilizza le visualizzazioni Android anziché Jetpack Compose per Wear OS, attiva l'opzione utilizzando AndroidManifest.xml. A differenza dell'ultima versione alpha di Wear Compose Material 3, che attiva automaticamente la barra di stato del sistema, le app basate su View devono attivare esplicitamente questa funzionalità aggiungendo il tag ENABLE_GLOBAL_STATUS_BAR <meta-data> all'interno di <application>:

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

Monitora gli inset della finestra superiore

Utilizza ViewCompat.setOnApplyWindowInsetsListener e controlla il valore di windowInsets.getInsets(WindowInsetsCompat.Type.statusBars()). Quando statusBarInsets.top > 0, rimuovi la UI precedente delle ore 12 e regola il padding superiore; in caso contrario, torna alla UI precedente:

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
}

Nascondere e mostrare la barra di stato in modo programmatico

A differenza di ScreenScaffold in Compose, le app basate su View devono nascondere o mostrare esplicitamente la barra di stato del sistema (ad esempio, quando si accede a una visualizzazione immersiva a schermo intero o si coordina il comportamento di scorrimento) utilizzando 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())

Testa la tua app

Quando testi la tua app sull'emulatore Wear OS 7.1 Beta Preview (API 37.2-beta1), controlla quanto segue:

L'orologio viene visualizzato una sola volta: verifica che solo l'ora della barra di stato del sistema venga visualizzata nella posizione delle ore 12 e che non venga sovrapposta da TimeText in-app legacy e contenuti dell'app.
Spaziatura interna superiore: verifica che i titoli delle schermate, le intestazioni e i pulsanti superiori vengano visualizzati sotto la barra di stato.
Overlay e finestre di dialogo a schermo intero: verifica che le finestre di dialogo, i selettori, gli stepper e le attività personalizzate a schermo intero nascondano la barra di stato quando vengono aperti e che la ripristinino quando vengono chiusi.