Condividi tramite


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:

    dependencies {
        implementation "androidx.window:window:1.0.0"
        implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.4.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à .

    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
    
  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.

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

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