WindowState

WindowState est une bibliothèque d’utilitaires pour Jetpack Compose qui vous permet d’obtenir facilement des détails sur l’état de fenêtre des appareils double écran, pliables et à écran large. Ces informations sont collectées à l’aide de la bibliothèque du Gestionnaire de fenêtres Jetpack de Google.

La classe WindowState fournit des informations sous la forme d’un état Compose, et inclut des propriétés telles que la position/l’orientation de la fonctionnalité de pliage, la catégorie de taille de fenêtre et le mode de la fenêtre. Les catégories de taille de fenêtre pour la hauteur et la largeur sont mesurées en fonction des recommandations officielles d’Android, et le mode de fenêtre actuel est déterminé par la fonctionnalité de pliage et l’orientation de l’appareil. Pour rappel, les modes de fenêtre sont des positions de l’écran qui tirent parti des facteurs de forme double écran et pliable. Il existe quatre modes possibles : Double écran portrait, Double écran paysage, Écran simple portrait et Écran simple paysage.

Ajouter une dépendance

1. Vérifiez que vous disposez du dépôt mavenCentral() dans votre fichier build.gradle de niveau supérieur :

   allprojects {
       repositories {
           google()
           mavenCentral()
        }
   }
   

2. Ajoutez la dépendance suivante au fichier build.gradle de niveau module (la version actuelle peut être différente de ce qui est illustré ici) :

   implementation "com.microsoft.device.dualscreen:windowstate:1.0.0-alpha07"
   

3. Vérifiez également que compileSdkVersion est défini sur API 33 et que targetSdkVersion est défini sur API 32 ou version ultérieure dans le fichier build.gradle au niveau du module.

   android { 
       compileSdkVersion 33
   
       defaultConfig { 
           targetSdkVersion 32
       } 
       ... 
   }
   

Utiliser WindowState dans votre projet

Pour utiliser la bibliothèque dans un projet Compose, appelez la fonction rememberWindowState() à partir de votre MainActivity. Cette méthode retourne un objet WindowState que vous pouvez passer à votre composable de niveau supérieur sous la forme d’un état.

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        setContent {
            ExampleAppTheme {
                ExampleApp(rememberWindowState())
            }
        }
    }
}

À l’intérieur de vos composables, vous pouvez ensuite accéder aux différentes propriétés de l’objet WindowState pour faire des choix quant à la disposition de votre application. Dans l’exemple ci-dessous, la méthode isDualScreen() est utilisée pour choisir entre deux dispositions différentes : une pour les appareils à écran simple et une pour les appareils à double écran.

fun ExampleApp(windowState: WindowState) {
    if (windowState.isDualScreen())
        DualScreenAppContent(windowState.foldSizeDp)
    else
        SingleScreenAppContent()
}

Pour des informations de référence plus détaillées sur les API, consultez le fichier LISEZ-MOI WindowState.

Calculer les tailles de volet

En plus d’exposer les informations sur le Gestionnaire de fenêtres Jetpack et les catégories de taille de fenêtre, la classe WindowState calcule également les tailles de volet pour deux dispositions de volet. Si le composant TwoPaneLayout n’est pas adapté à votre projet, vous pouvez utiliser les propriétés largeScreenPane1Weight, pane1SizeDp et pane2SizeDp pour configurer vos propres dispositions personnalisées :

fun ExampleApp(windowState: WindowState) {
    windowState.largeScreenPane1Weight = 0.3f
    
    CustomListDetailLayout(
        pane1Width = windowState.pane1SizeDp.width,
        pane2Width = windowState.pane2SizeDp.width,
        list = { ListContent() },
        detail = { DetailContent() }
    )
}

Les tailles de volet sont calculées en fonction de la logique suivante :

• Si une fenêtre contient une fonctionnalité de pliage de séparation :
  • Calculez la taille des volets en fonction des limites de la fonctionnalité de pliage
• Si une fenêtre est considérée comme grande (EXPANDED classes de taille de largeur et au moins MEDIUM de hauteur) :
  • Calculez la taille des volets en fonction de la propriété largeScreenPane1Weight, de la taille de la fenêtre et de l’orientation de l’appareil
• Si l’appareil n’est pas pliable ou à écran large :
  • Un seul volet doit être affiché, donc retournez la taille de volet 0

Notez que ces vérifications logiques sont effectuées dans l’ordre. Par conséquent, il est possible qu’un grand appareil pliable soit considéré à écran large si sa fonction de pliage n’est pas une fonction de pliage de séparation, ce qui signifie que l’appareil n’a pas de charnière et est plat.

Nous recommandons d’utiliser les propriétés décrites ci-dessus pour fournir une prise en charge des écrans pliables et des écrans larges. Toutefois, si vous avez besoin d’utiliser des tailles de volet uniquement en cas de présence d’une fonctionnalité de pliage de séparation, vous pouvez utiliser les propriétés foldablePane1SizeDp et foldablePane2SizeDp à la place :

fun ExampleApp(windowState: WindowState) {
    CustomCompanionPaneLayout(
        pane1Size = windowState.foldablePane1SizeDp,
        pane2Size = windowState.foldablePane2SizeDp,
        game = { GameScreen() },
        controls = { ControlPanel() }
    )
}

Exemples

Pour obtenir d’autres exemples d’utilisation de WindowState, consultez l’exemple de bibliothèque et nos exemples Compose.