Coordonner votre UI avec la barre d'état du système

Jusqu'à Wear OS 7 (API 37), la plate-forme n'affichait pas de barre d'état système sur les fenêtres d'application. Les applications occupaient tout l'écran et pouvaient afficher n'importe quel contenu en haut (à 12 heures), comme une horloge TimeText intégrée, des en-têtes incurvés personnalisés ou des commandes supérieures.

À partir de Wear OS 8 (et disponible dès maintenant pour les tests en preview anticipée dans l'émulateur Wear OS 7.1 Beta Preview (API 37.2-beta1)), le système affiche une barre d'état au-dessus des fenêtres de l'application à la position 12 heures pour afficher l'heure et les indicateurs d'état. Pour éviter tout chevauchement avec la barre d'état du système, les applications doivent arrêter d'afficher leur propre horloge (TimeText) et respecter les encarts de la fenêtre de la barre d'état supérieure (gérés automatiquement par AppScaffold et ScreenScaffold à partir de Wear Compose 1.8), ou masquer la barre d'état du système lorsqu'une expérience immersive en plein écran est nécessaire.

Barre d'état du système dans Wear OS 8
Figure 1. Barre d'état du système dans Wear OS 8.

Les principaux avantages sont les suivants :

  • Cohérence visuelle : typographie, emplacement et plaque arrière de l'horloge uniformes dans tout le système et toutes les applications.
  • Indicateurs d'état du système : permet à la plate-forme d'afficher des icônes d'état (telles que les indicateurs de micro et de localisation actifs, l'état de la connectivité ou les informations sur la batterie) et l'heure sur les surfaces. Une seule icône s'affiche à la fois, en fonction de la priorité.
  • Coordination automatique du défilement et des transitions : lorsqu'elle est associée à Jetpack Compose pour Wear OS 1.8, la barre d'état du système se masque automatiquement lorsque les utilisateurs font défiler le contenu et réapparaît après un court délai d'inactivité (2 s).

Configurer votre application

Pour commencer, suivez les étapes préalables ci-dessous :

  1. Installez la version preview d'Android Studio (Canary).
  2. Dans SDK Manager, téléchargez l'image système de l'émulateur Wear OS 7.1 Preview (API 37.2-beta1). Cette version fournit un accès anticipé à la barre d'état du système Wear OS 8 avant le SDK Wear OS 8.
  3. Dans le Gestionnaire d'appareils, créez et lancez un appareil virtuel Wear OS à l'aide de l'image API 37.2-beta1.

Pour prendre en charge la barre d'état du système dans votre application, mettez à jour la version targetSdk de votre application vers la version 35 ou une version ultérieure. La plate-forme n'active la barre d'état du système que pour les applications ciblant l'API 35 ou une version ultérieure afin de préserver la rétrocompatibilité des anciennes applications. Mettez également à jour vos dépendances Wear Compose vers la dernière version alpha (actuellement 1.8.0-alpha02), comme indiqué dans l'extrait de code suivant. Si votre application utilise une ancienne version de Wear Compose, vous pouvez utiliser la compétence de migration vers Wear Compose Material 3 pour faciliter la migration.

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

Utiliser la barre d'état du système

Dans la dernière version alpha de Wear Compose Material 3 1.8.0 (actuellement 1.8.0-alpha02), la bibliothèque active automatiquement votre application en fusionnant la propriété com.google.wear.ENABLE_GLOBAL_STATUS_BAR <meta-data> dans votre AndroidManifest.xml. Au moment de l'exécution, AppScaffold et ScreenScaffold vérifient si la barre d'état du système est activée sur l'appareil et si cette propriété d'activation du fichier manifeste est définie sur true :

  • Sur l'émulateur Preview/Wear OS 8 ou version ultérieure (si l'option est activée) : AppScaffold supprime son TimeText interne afin que la barre d'état du système s'affiche correctement à la position 12 heures sans duplication. ScreenScaffold recalcule contentPadding pour prendre en compte les limites d'encart de la barre d'état, et coordonne le masquage et l'affichage de la barre d'état lorsque l'utilisateur fait défiler la liste.
  • Sur les appareils Wear OS 7 et versions antérieures (ou lorsque l'utilisateur n'a pas activé l'option) : AppScaffold revient automatiquement à l'affichage de l'TimeText standard dans l'application, ce qui permet de maintenir une rétrocompatibilité totale à partir d'un codebase unique.
@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}")
                    }
                }
            }
        }
    }
}

Voici ce qui se passe lorsque vous exécutez l'exemple :

  • Au repos (en haut de la liste) : la barre d'état du système s'affiche à la position "12 heures". L'en-tête "Hello Status Bar" se trouve sous la zone d'encart de la barre d'état, sans coupure ni chevauchement.
  • Défilement vers le bas : lorsque vous faites défiler les éléments de la liste, la barre d'état est masquée et les éléments de la liste défilent d'un bord à l'autre derrière la bordure supérieure.
  • Inactif : lorsque vous arrêtez de faire défiler l'écran et que vous le relâchez, la barre d'état réapparaît automatiquement après environ deux secondes.

Gérer les scénarios et les personnalisations courants

Les sections suivantes décrivent comment gérer les scénarios courants que vous pouvez rencontrer lorsque vous utilisez la barre d'état du système.

Gérer les écrans non déroulants (statiques)

Sur les écrans qui utilisent une mise en page statique (comme Column ou Box) plutôt qu'une liste déroulante, appliquez la contentPadding fournie par ScreenScaffold à votre mise en page racine afin que les éléments d'interface utilisateur supérieurs ne chevauchent pas la barre d'état du système :

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

Utiliser des composants interactifs en plein écran

Les composants interactifs en plein écran de Wear Compose Material 3 (y compris AlertDialog, Dialog, Stepper, TimePicker et DatePicker) masquent automatiquement la barre d'état du système lorsqu'ils sont affichés à l'écran, de sorte que leurs commandes aient un accès complet au haut de l'écran circulaire. Lorsqu'elle est fermée, la barre d'état du système est automatiquement restaurée à l'aide de l'API du contrôleur d'encarts de fenêtre.

Passer en mode immersif

Pour passer en mode immersif, dans lequel la barre d'état du système et la TimeText locale sont masquées, ajoutez le composable StatusBarSuppression à votre application ou à votre écran. Réservez le mode immersif aux écrans que l'utilisateur voit brièvement (superpositions de confirmation, boîtes de dialogue) ou qui utilisent l'intégralité de l'écran (indicateurs de progression en plein écran).

Quand utiliser le mode immersif au niveau de l'écran ?

Si seul un écran spécifique de votre application doit être en plein écran/immersif, appelez StatusBarSuppression() dans le contenu de ScreenScaffold. ScreenScaffold supprime automatiquement la barre d'état du système (et omet la marge intérieure de la barre d'état supérieure) lorsque cet écran est actif, puis restaure la barre d'état du système lorsque vous revenez à d'autres écrans :

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

Déterminer quand utiliser le mode immersif au niveau de l'application

Si l'ensemble de votre application (ou Activity) est une expérience immersive en plein écran sur tous les écrans, utilisez StatusBarSuppression au niveau de AppScaffold et encapsulez votre contenu pour supprimer la barre d'état du système sur tous les écrans :

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

Afficher les remplacements de texte d'heure personnalisés

Si vous devez afficher un en-tête incurvé personnalisé ou désactiver temporairement la barre d'état du système sur un écran spécifique ou dans l'ensemble de votre application lors de la migration vers Wear OS 8, transmettez un composable timeText personnalisé pour supprimer la barre d'état du système :

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

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

Implémenter à l'aide de vues (non recommandé)

Si votre application utilise des vues Android plutôt que Jetpack Compose pour Wear OS, activez l'option à l'aide de AndroidManifest.xml. Contrairement à la dernière version alpha de Wear Compose Material 3, qui active automatiquement la barre d'état du système, les applications basées sur les vues doivent l'activer explicitement en ajoutant la balise ENABLE_GLOBAL_STATUS_BAR <meta-data> dans <application> :

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

Surveiller les encarts de la fenêtre supérieure

Utilisez ViewCompat.setOnApplyWindowInsetsListener et vérifiez la valeur de windowInsets.getInsets(WindowInsetsCompat.Type.statusBars()). Lorsque statusBarInsets.top > 0, supprimez l'ancienne UI de 12 heures et ajustez la marge intérieure supérieure. Sinon, revenez à l'ancienne 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
}

Masquer et afficher la barre d'état de manière programmatique

Contrairement à ScreenScaffold dans Compose, les applications basées sur les vues doivent explicitement masquer ou afficher la barre d'état du système (par exemple, lors de l'accès à une vue immersive en plein écran ou de la coordination du comportement de défilement) à l'aide de 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())

Tester votre application

Lorsque vous testez votre application sur l'émulateur de la version bêta de Wear OS 7.1 (API 37.2-beta1), vérifiez les points suivants :

  • L'horloge n'apparaît qu'une seule fois : vérifiez que seule l'heure de la barre d'état du système s'affiche à la position 12 heures et qu'aucun ancien TimeText intégré à l'application ni contenu de l'application ne la chevauche.
  • Marge intérieure supérieure : vérifiez que les titres d'écran, les en-têtes et les boutons supérieurs s'affichent sous la barre d'état.
  • Superpositions et boîtes de dialogue en plein écran : vérifiez que les boîtes de dialogue, les sélecteurs, les steppers et les activités personnalisées en plein écran masquent la barre d'état lorsqu'ils sont ouverts et qu'ils la restaurent lorsqu'ils sont fermés.