Jetpack Window Manager per dispositivi pieghevoli

Jetpack Window Manager offre un'API standard per l'uso di tutti i dispositivi piegabili. Contiene due classi importanti:

• DisplayFeature: identifica eventuali discontinuità presenti sulla superficie dello schermo piatto, ad esempio cerniere o piegature. Window Manager restituirà una raccolta di funzionalità di visualizzazione da un callback di modifica del layout.
• FoldingFeature : fornisce informazioni su una funzionalità specifica del dispositivo. Anche se Surface Duo ha una sola funzionalità di riduzione, è possibile che altri dispositivi abbiano più dispositivi.

Una guida simile è disponibile in Android Foldable Codelab. Per altre informazioni sullo sviluppo per le riduzioni, vedere la documentazione di Android. Gli esempi del team Android sono disponibili anche in GitHub. Le note sulla versione di Jetpack registrano le modifiche apportate a Window Manager non appena vengono aggiornate.

Suggerimento

I controlli e le classi helper disponibili nella libreria per dispositivi a doppio schermo Surface Duo funzionano con Window Manager. Seguire le istruzioni per aggiungere i pacchetti corretti al progetto dell'app.

Per usare Window Manager direttamente nel codice, seguire le istruzioni seguenti:

Aggiungere le dipendenze

1. Assicurarsi di avere il mavenCentral() repository nel file build.gradle di primo livello:

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

2. Verificare che e targetSdkVersion siano impostati sull'API compileSdkVersion 31 o versione successiva nel file build.gradle a livello di modulo:

   android { 
       compileSdkVersion 31
   
       defaultConfig { 
           targetSdkVersion 31
       } 
       ... 
   }
   
   

3. Aggiungere le dipendenze seguenti al file build.gradle a livello di modulo:

   Visualizzazioni

   dependencies {
       implementation "androidx.window:window:1.0.0"
       implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.4.0'
   }
   

   Compose

   dependencies {
       implementation "androidx.window:window:1.0.0"
   }
   

Usare Window Manager nel codice Kotlin

Quando si accede alle proprietà di Window Manager nei progetti Kotlin, è importante configurare il flusso corretto di informazioni. In caso contrario, potresti ricevere un numero eccessivo di aggiornamenti degli eventi e le prestazioni dell'app potrebbero essere influenzate.

Per inizializzare e usare un WindowInfoTracker oggetto, seguire questa procedura:

1. Nella classe MainActivity creare una variabile per .WindowInfoTracker Assicurarsi che import androidx.window.layout.WindowInfoTracker venga aggiunto all'inizio del file.

   class MainActivity : AppCompatActivity() {
       private lateinit var windowInfoTracker: WindowInfoTracker
   

2. Inizializzare nel WindowInfoTracker metodo dell'attività onCreate e configurare un flusso per raccogliere informazioni dalla windowLayoutInfo proprietà .

   Visualizzazioni

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       // Initialize the window manager
       windowInfoTracker = WindowInfoTracker.getOrCreate(this@MainActivity)
   
       // Set up a flow
       lifecycleScope.launch(Dispatchers.Main) {
           lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
               windowInfoTracker.windowLayoutInfo(this@MainActivity)
                   .collect { 
                       // Check FoldingFeature properties here
                   }
           }
       }
   }
   

   Assicurarsi che queste importazioni vengano aggiunte anche all'inizio del file:

   import androidx.lifecycle.Lifecycle
   import androidx.lifecycle.lifecycleScope
   import androidx.lifecycle.repeatOnLifecycle
   import kotlinx.coroutines.Dispatchers
   import kotlinx.coroutines.flow.collect
   import kotlinx.coroutines.launch
   

   Compose

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       // Initialize the window manager
       windowInfoTracker = WindowInfoTracker.getOrCreate(this@MainActivity)
   
       setContent {
           ExampleAppTheme {
               ExampleApp(windowInfoTracker.windowLayoutInfo(this@MainActivity))
           }
       }
   }
   
   @Composable
   fun ExampleApp(windowLayoutInfo: Flow<WindowLayoutInfo>) {
       // Set up a flow   
       LaunchedEffect(windowLayoutInfo) {
           windowLayoutInfo.collect { 
               // Check FoldingFeature properties here
           }
       }
   }
   

   Assicurarsi che queste importazioni vengano aggiunte anche all'inizio del file:

   import androidx.compose.runtime.LaunchedEffect
   import kotlinx.coroutines.flow.Flow
   import kotlinx.coroutines.flow.collect
   

3. Aggiungere il codice per controllare il flusso per verificare le WindowLayoutInfoproprietà delle funzionalità di riduzione. Quando questo codice viene eseguito, l'attività verrà aggiornata con il comportamento del dispositivo corrente e le funzionalità di visualizzazione (se si estende su una piega o una cerniera).

   Nel frammento di codice seguente l'attività visualizza testo diverso in base alle proprietà di un oggetto FoldingFeature.

   Visualizzazioni

   In questo esempio è presente un controllo TextView denominato layout_change_text che mostra il tipo di occlusione e isSeparating il valore per le funzionalità di riduzione rilevate.

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       windowInfoTracker = WindowInfoTracker.getOrCreate(this@MainActivity)
   
       lifecycleScope.launch(Dispatchers.Main) {
           lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
               windowInfoTracker.windowLayoutInfo(this@MainActivity)
                   .collect { newLayoutInfo ->
                       layout_change_text.text = "No display features detected"
                       for (displayFeature : DisplayFeature in newLayoutInfo.displayFeatures) {
                           if (displayFeature is FoldingFeature && displayFeature.occlusionType == FoldingFeature.OcclusionType.NONE) {
                               layout_change_text.text = "App is spanned across a fold, " +
                                   "isSeparating = ${displayFeature.isSeparating}"
                           }
                           if (displayFeature is FoldingFeature && displayFeature.occlusionType == FoldingFeature.OcclusionType.FULL) {
                               layout_change_text.text = "App is spanned across a hinge, " +
                                   "isSeparating = ${displayFeature.isSeparating}"
                           }
                       }
                   }
           }
       }
   }
   

   Compose

   In questo esempio è presente un elemento Text che mostra le dimensioni e isSeparating il valore per le funzionalità di riduzione rilevate.

   @Composable
   fun ExampleApp(windowLayoutInfo: Flow<WindowLayoutInfo>) {
       var isSeparating by remember { mutableStateOf(false) }
       var foldSizePx by remember { mutableStateOf(0) }
   
       LaunchedEffect(windowLayoutInfo) {
           windowLayoutInfo.collect { newLayoutInfo ->
                   val displayFeatures = newLayoutInfo.displayFeatures
   
                   if (displayFeatures.isNotEmpty()) {
                       val foldingFeature = displayFeatures.first() as FoldingFeature
   
                       // Check if a folding feature separates content into two sections
                       isSeparating = foldingFeature.isSeparating
   
                       // Get size of folding feature in pixels
                       foldSizePx = when (foldingFeature.orientation) {
                           FoldingFeature.Orientation.VERTICAL -> foldingFeature.bounds.width()
                           else -> foldingFeature.bounds.height()
                       }
                   }
               }
       }
   
       Text(text = "Fold size: $foldSizePx pixels, isSeparating = $isSeparating")
   }
   

Proprietà delle funzionalità di riduzione

La WindowLayoutInfo classe ha una raccolta di DisplayFeature elementi, una o più delle quali possono essere istanze della classe FoldingFeature.

Le funzionalità di riduzione hanno le proprietà seguenti:

• bounds - coordinate del rettangolo di delimitazione di una caratteristica di riduzione
• occlusionType - se una funzionalità di riduzione nasconde il contenuto (FULL o NONE)
• orientation - orientamento di una caratteristica di riduzione (HORIZONTAL o VERTICAL)
• state - angolo di una caratteristica di riduzione (HALF_OPENED o FLAT)
• isSeparating - se una caratteristica di riduzione separa l'area di visualizzazione in due sezioni distinte

È possibile eseguire una query su queste proprietà per prendere decisioni su come modificare il layout dopo le modifiche alla configurazione.

isSeparating

Quando si decide dove posizionare i controlli o il numero di riquadri di contenuto da visualizzare, utilizzare la proprietà isSeparating . Questo campo garantisce che l'app offra la migliore esperienza utente in tutti i dispositivi piegabili:

• Per i dispositivi a doppio schermo, questo sarà sempre vero quando un'app viene estesa attraverso la cerniera
• Per altri dispositivi piegabili, questo sarà vero solo quando lo stato è HALF_OPENED, ad esempio quando un dispositivo si trova nella posizione di tabella superiore

Usa la isSeparating proprietà per decidere se adattare il layout dell'interfaccia utente dell'app per un dispositivo piegabile o usa l'interfaccia utente predefinita quando non è presente alcuna separazione:

private fun updateCurrentLayout(newLayoutInfo: WindowLayoutInfo) {
   for (displayFeature in newLayoutInfo.displayFeatures) {
       val foldFeature = displayFeature as? FoldingFeature
       foldFeature?.let {
           if (it.isSeparating) {
               // The content is separated by the FoldingFeature.
               // Here is where you should adapt your UI.
           } else {
               // The content is not separated.
               // Users can see and interact with your UI properly.
           }
       }
   }
}

Per un esempio più dettagliato di come usare questo campo, vedere questo esempio isSeparating.

Google fornisce anche documentazione ed esempi correlati a questa proprietà come parte delle linee guida per schermi di grandi dimensioni e piegabili.

Esempi

Il repository surface-duo-jetpack-window-manager-samples GitHub contiene diversi esempi di Kotlin che illustrano diversi modelli di esperienza utente a doppio schermo creati usando Jetpack Window Manager e il sistema di visualizzazione tradizionale.

Il repository surface-duo-compose-samples GitHub include anche esempi di Kotlin a doppio schermo che usano Jetpack Window Manager, ma in questi esempi l'interfaccia utente è compilata con Jetpack Compose.

API Java

Fare riferimento al post di blog di Jetpack Window Manager con Java e a questo esempio Java per informazioni su come accedere alla WindowInfoTracker classe tramite .WindowInfoTrackerCallbackAdapter

Risorse

• Informazioni di riferimento sulle API androidx.window.layout
• Esempi del team Android
• Supportare nuovi fattori di forma con la nuova libreria di Jetpack Window Manager
• Video: Sviluppo per dispositivi pieghevoli
• Esempio di Codelab di Window Manager (GibHub)
• Jetpack Window Manager Changelog.