Estensioni WindowManager

Jetpack WindowManager consente agli sviluppatori di applicazioni di supportare nuovi fattori di forma dei dispositivi e ambienti multi-finestra.

WindowManager Extensions (Estensioni) è un modulo della piattaforma Android attivabile che attiva una varietà di funzionalità di Jetpack WindowManager. Il modulo è implementato in AOSP in frameworks/base/libs/WindowManager/Jetpack su dispositivi che supportano le funzionalità WindowManager.

Distribuzione del modulo Estensioni

Le estensioni vengono compilate in una libreria .jar e inserite nell'elemento system_ext su un dispositivo se le Estensioni sono abilitate nel makefile del dispositivo.

Per attivare le estensioni su un dispositivo, aggiungi quanto segue al dispositivo del prodotto Makefile:

$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)

In questo modo, androidx.window.extensions e androidx.window.sidecar di pacchetti sul dispositivo e imposta la proprietà persist.wm.extensions.enabled. Se includi questi pacchetti nel makefile, le dichiarazioni vengono inserite anche nella etc/permissions/, rendendole disponibili per i processi di applicazione. Di solito vengono caricati ed eseguiti come parte del processo dell'applicazione quando utilizzato dalla libreria Jetpack WindowManager, che ne rende un'operazione simile al codice del framework lato client, come mostrato di seguito figura:

. Figura 1. Estensioni WindowManager caricate nell'applicazione simile al codice della piattaforma.

Il modulo androidx.window.extensions è l'attuale modulo Estensioni di sviluppo attivo. Il modulo androidx.window.sidecar è un modulo precedente inclusi per garantire la compatibilità con le prime versioni di Jetpack WindowManager, ma il file collaterale non è più gestito attivamente.

La figura seguente mostra la logica per determinare l'uso di androidx.window.extensions o androidx.window.sidecar.

. Figura 2. Albero decisionale per l'accesso androidx.window.extensions o androidx.window.sidecar.

Moduli di estensioni

Le estensioni offrono funzionalità di windowing per i dispositivi pieghevoli con schermi di grandi dimensioni e dispositivi che supportano il windowing su display esterni. Le aree delle caratteristiche includono:

Le implementazioni OEM delle estensioni possono fornire componenti o componenti nulli con le implementazioni predefinite o stub dei metodi nella WindowExtensions se l'hardware del dispositivo non supporta le funzionalità corrispondenti a meno che la funzione non sia richiesta specificatamente in Compatibility Definition Document (CDD) 7.1.1.1.

Estensioni e API Jetpack

Il modulo Estensioni di WindowManager offre una propria piattaforma API, oltre a le API della piattaforma pubblica. Il modulo Estensioni è sviluppato pubblicamente in androidx.window.extensions non rivolto agli sviluppatori nella libreria Jetpack, in modo che Jetpack WindowManager (androidx.window) al momento della compilazione. In genere l'API Extensions e offre API di livello inferiore.

Le API fornite dalle estensioni sono pensate per essere utilizzate dal Jetpack Solo libreria WindowManager. Le API Extensions non sono concepite per essere chiamate sviluppatori di applicazioni. La libreria delle estensioni non deve essere aggiunta come per un'applicazione nel file di build Gradle per garantire che funzionalità. Evita di precompilare la libreria delle estensioni in un'applicazione directly; si basa sul caricamento del runtime per evitare il caricamento di un mix di classi di estensioni precompilate e fornite dal runtime.

Jetpack WindowManager (androidx.window) deve essere aggiunto come applicazione e fornisce le API pubbliche rivolte agli sviluppatori, incluse quelle per le funzionalità delle estensioni WindowManager. La libreria WindowManager automaticamente carica le estensioni nel processo dell'applicazione e aggrega i file di livello inferiore Estensione delle API in astrazioni di livello superiore e maggiore concentrazione interfacce. Le API Jetpack di WindowManager seguono gli standard della per lo sviluppo di applicazioni Android e sono pensate per fornire pratiche l'interoperabilità integrandosi bene con i codebase che utilizzano altri AndroidX librerie.

Versioni e aggiornamenti delle estensioni

Il modulo Estensioni può essere aggiornato insieme alla piattaforma Android annualmente oppure aggiornamenti trimestrali. Grazie agli aggiornamenti trimestrali, il livello API Extensions è aumentato tra gli aggiornamenti delle API della piattaforma Android, consentendo un'iterazione più rapida e offrendo agli OEM l'opportunità di aggiungere l'accesso ufficiale all'API per le nuove funzionalità vicino al lancio dell'hardware.

La tabella seguente elenca le versioni API androidx.window.extensions per diverse release di Android.

Versione della piattaforma Android Livello API WindowManager Extensions Versione API androidx.window.extensions
Android 15 6 1.5.0 (disponibile a breve)
Android 14 QPR3 5 1.4.0 (disponibile a breve)
Android 14 QPR1 4 1.3.0
Android 14 3 1.2.0
Android 13 QPR3 2 1.1.0
Android 13 1 1.0.0
Android 12L 1 1.0.0

Il livello API Extensions (colonna centrale) viene aumentato ogni volta che c'è oltre alla superficie API stabile esistente (colonna destra).

Compatibilità con le versioni precedenti e successive

Jetpack WindowManager gestisce la complessità della gestione di livelli API frequenti aggiornamenti, rapida evoluzione delle API e compatibilità con le versioni precedenti. Quando il codice libreria durante la procedura di richiesta, la libreria controlla le di API di Google Extensions e fornisce accesso alle funzionalità in base alle livello.

Per proteggere un'applicazione dagli arresti anomali in fase di runtime, WindowManager esegue anche un controllo di riflessione Java di runtime delle API per le estensioni disponibili secondo il livello API Extensions dichiarato. In caso di mancata corrispondenza, WindowManager può disattivare l'utilizzo delle Estensioni (in parte o del tutto) e segnalare i contenuti pertinenti non disponibili per l'applicazione.

Le estensioni WindowManager sono implementate come modulo system_ext che utilizza le API della piattaforma privata per richiamare il core di WindowManager, DeviceStateManager, e altri servizi di sistema nell'implementazione delle funzionalità delle estensioni.

La compatibilità non può essere mantenuta con le versioni pre-release delle estensioni prima del rilascio della piattaforma Android trimestrale o annuale corrispondente con di cui le versioni sono finalizzate. La cronologia completa delle API Extensions può essere trovato nel ramo di rilascio window:extensions:extensions file di testo delle API.

Le versioni più recenti delle estensioni devono continuare a funzionare con le versioni precedenti di WindowManager compilato in applicazioni per mantenere la compatibilità in avanti. A assicura che ogni nuova versione dell'API Extensions aggiunga solo nuove API e non rimuove quelli meno recenti. Di conseguenza, le applicazioni con la versione precedente di WindowManager possono continuare a utilizzare le API Extensions precedenti in cui le app erano compilate contro i guasti.

La verifica CTS assicura che, per qualsiasi versione dichiarata delle API per le estensioni nel dispositivo, tutte le API corrispondenti e quelle precedenti sono presenti e funzionanti.

Prestazioni

Per impostazione predefinita, il modulo Estensioni viene memorizzato nella cache in caricatori di classi di sistema non-bootclasspath a partire da Android 14 (livello API 34), quindi non c'è alcun impatto sulle prestazioni dovuto al caricamento del modulo in memoria all'avvio dell'app. L'uso di funzionalità dei singoli moduli potrebbe avere una leggera influenza sulle caratteristiche prestazionali delle app quando vengono eseguite altre chiamate IPC tra il client e il server.

Moduli

Incorporamento delle attività

La sezione Incorporamento delle attività fornisce un insieme di funzionalità che consentono alle applicazioni di organizzare presentazione della finestra delle attività entro i limiti dell'applicazione principale. Questo include la visualizzazione di due attività affiancate contemporaneamente in un layout a più riquadri, che facilita l'ottimizzazione degli schermi di grandi dimensioni per le versioni diverse applicazioni.

Il componente di incorporamento delle attività deve essere disponibile su tutti i dispositivi con un display integrato di dimensioni uguali o superiori a sw600 dp. L'incorporamento delle attività deve essere abilitato anche sui dispositivi che supportano il display esterno poiché l'applicazione potrebbe essere visualizzata in dimensioni maggiori quando i display sono connessi in fase di esecuzione.

Configurazione dispositivo

Non è necessaria alcuna configurazione dispositivo specifica se non abilitare le estensioni come descritto in Distribuzione del modulo Estensioni . È opportuno attivare le estensioni su tutti i dispositivi che supportano modalità multi-finestra. È probabile che le estensioni di Android delle future versioni richiesta per le configurazioni di dispositivi portatili e con schermi di grandi dimensioni.

Informazioni sulla disposizione delle finestre

Il componente Informazioni layout finestra identifica la posizione e lo stato del su un dispositivo pieghevole quando la cerniera attraversa una finestra di applicazione. Le informazioni sul layout delle finestre consentono alle applicazioni di rispondere e mostrare layout in modalità da tavolo sui pieghevoli. Consulta Fai attenzione alla tua app per i dettagli di utilizzo.

Dispositivi Android pieghevoli che includono una cerniera che collega i dispositivi le aree del pannello display continuo devono rendere le informazioni sulla cerniera disponibile per le applicazioni fino al giorno WindowLayoutComponent.

La posizione della cerniera e i limiti devono essere riportati in relazione all'applicazione finestra identificata da un Context passato all'API. Se la finestra dell'applicazione i limiti non si intersecano con i limiti della cerniera, DisplayFeature non devono essere segnalati. È inoltre accettabile non segnalare le caratteristiche del display quando la loro posizione potrebbe non essere riportata in modo affidabile, come quando la finestra può essere spostata liberamente dall'utente in modalità multi-finestra oppure compatibilità con la modalità letterbox.

Per le funzionalità di piegatura, è necessario segnalare gli aggiornamenti dello stato quando la posizione della cerniera cambia tra stati stabili. Per impostazione predefinita, in modalità di visualizzazione fissa, l'API deve segnalare FoldingFeature.State.FLAT Se l'hardware del dispositivo può essere lasciato in modalità semipiegata in stato stabile, L'API deve segnalare FoldingFeature.State.HALF_OPENED. Non esiste uno stato chiuso nell'API, poiché in questo caso la finestra dell'applicazione non sarebbero visibili o non varcherebbero i limiti della cerniera.

Configurazione dispositivo

Per supportare l'implementazione della funzionalità pieghevole, gli OEM devono:

  • Configura in device_state_configuration.xml gli stati del dispositivo utilizzati da DeviceStateManagerService. Consulta DeviceStateProviderImpl.java come riferimento.

    Se le implementazioni predefinite di DeviceStateProvider oppure DeviceStatePolicy non sono adatti al dispositivo, è possibile utilizzare un'implementazione personalizzata.

  • Attiva il modulo Estensioni come descritto in Sezione Distribuzione dei moduli estensioni.

  • Specifica la posizione delle funzionalità di visualizzazione nell'com.android.internal.R.string.config_display_features risorsa stringa (di solito in frameworks/base/core/res/res/values/config.xml nell'overlay del dispositivo).

    Il formato previsto per la stringa è:

    <type>-[<left>,<top>,<right>,<bottom>]

    type può essere fold o hinge. Valori per left, top, right e bottom sono coordinate di pixel intere nello spazio di coordinate di visualizzazione in l'orientamento naturale del display. La stringa di configurazione può contenere più le caratteristiche separate da un punto e virgola.

    Ad esempio:

    <!-- Jetpack WindowManager display features -->
<string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>

  • Definisci la mappatura tra gli identificatori di stato dei dispositivi interni utilizzati in DeviceStateManager e le costanti pubbliche inviate agli sviluppatori in com.android.internal.R.array.config_device_state_postures.

    Il formato previsto per ogni voce è:

    <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

    Gli identificatori di stato supportati sono:

    • COMMON_STATE_NO_FOLDING_FEATURES = 1: lo stato non ha elementi pieghevoli per report. Ad esempio, può essere lo stato chiuso del tipico dispositivo con la schermata principale sul lato interno.
    • COMMON_STATE_HALF_OPENED = 2: la funzionalità di chiusura è aperta a metà.
    • COMMON_STATE_FLAT = 3: la funzionalità di chiusura è piatta. Ad esempio, può essere lo stato aperto di un tipico dispositivo ripiegato con la schermata principale sul lato interno.
    • COMMON_STATE_USE_BASE_STATE = 1000: dentro Android 14, un valore che può essere usato per l'emulazione stati in cui lo stato cerniera deriva dallo stato base, come definito CommonFoldingFeature.java

    Per ulteriori informazioni, visita la pagina DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int).

    Ad esempio:

    <!-- Map of System DeviceState supplied by DeviceStateManager to WindowManager posture.-->
<string-array name="config_device_state_postures" translatable="false">
    <item>0:1</item>    <!-- CLOSED       : COMMON_STATE_NO_FOLDING_FEATURES -->
    <item>1:2</item>    <!-- HALF_OPENED  : COMMON_STATE_HALF_OPENED -->
    <item>2:3</item>    <!-- OPENED       : COMMON_STATE_FLAT -->
    <item>3:1</item>    <!-- REAR_DISPLAY : COMMON_STATE_NO_FOLDING_FEATURES -->
    <item>4:1000</item> <!-- CONCURRENT   : COMMON_STATE_USE_BASE_STATE -->
</string-array>

Area finestra

Il componente finestra area fornisce un insieme di caratteristiche che forniscono alle applicazioni l'accesso a display e aree di visualizzazione aggiuntivi su alcuni dispositivi pieghevoli dispositivi multi-display.

La modalità di visualizzazione posteriore consente a un'applicazione di mostrare l'interfaccia utente di anteprima della fotocamera sui cover del display di un dispositivo pieghevole per consentire l'uso della fotocamera principale del dispositivo per selfie e video. Dispositivi con un dispositivo Android compatibile (come definito dal CDD di Android in termini di attributi quali dimensioni, densità e gli inviti di navigazione disponibili) coprono il display in linea con il dispositivo posteriore devono fornire l'accesso alla modalità schermo posteriore.

Su Android 14, la modalità Dual Screen consente alle applicazioni eseguite sul display interno di un dispositivo pieghevole di mostrare contenuti aggiuntivi sul display di copertina rivolto ad altri utenti. Ad esempio, la visualizzazione della copertina può mostrare l'anteprima della fotocamera alla persona fotografata o registrata.

Configurazione dispositivo

Per supportare l'implementazione della funzionalità pieghevole, gli OEM devono:

  • Configura in device_state_configuration.xml gli stati del dispositivo utilizzati da DeviceStateManagerService. Consulta DeviceStateProviderImpl.java per ulteriori informazioni.

    Se l'implementazione predefinita DeviceStateProvider oppure DeviceStatePolicy non è adatta al dispositivo, è possibile usare un'implementazione personalizzata.

  • Per i dispositivi pieghevoli che supportano la modalità aperta o aperta, specifica il identificatori di stato in com.android.internal.R.array.config_openDeviceStates.

  • Per i dispositivi in-pieghevoli che supportano lo stato piegato, elenca i corrispondenti identificatori di stato in com.android.internal.R.array.config_foldedDeviceStates.

  • Per dispositivi pieghevoli che supportano lo stato semiaperto (la cerniera è aperta a metà ad esempio un laptop), elenca gli stati corrispondenti com.android.internal.R.array.config_halfFoldedDeviceStates.

  • Per i dispositivi che supportano la modalità schermo posteriore:

    • Elenca gli stati corrispondenti in com.android.internal.R.array.config_rearDisplayDeviceStates per DeviceStateManager.
    • Specifica l'indirizzo di visualizzazione fisico del display posteriore in com.android.internal.R.string.config_rearDisplayPhysicalAddress.
    • Specifica l'identificatore dello stato in com.android.internal.R.integer.config_deviceStateRearDisplay che deve essere utilizzato dalle estensioni.
    • Aggiungi l'identificatore di stato in com.android.internal.R.array.config_deviceStatesAvailableForAppRequests per renderlo disponibile alle applicazioni.

  • Su Android 14, per i dispositivi che supportano la modalità di visualizzazione doppia (simultanea):

    • Imposta com.android.internal.R.bool.config_supportsConcurrentInternalDisplays su true.
    • Specifica l'indirizzo di visualizzazione fisico del display posteriore in com.android.internal.R.config_deviceStateConcurrentRearDisplay.
    • Specifica in com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay l'identificatore dello stato che deve essere utilizzato dalle estensioni se l'identificatore deve essere reso disponibile per le applicazioni.
    • Aggiungi l'identificatore di stato in com.android.internal.R.array.config_deviceStatesAvailableForAppRequests per renderlo disponibile alle applicazioni.

Verifica

Gli OEM devono verificare le implementazioni per garantire il comportamento previsto in comune diversi scenari. I test CTS e i test effettuati con Jetpack WindowManager sono disponibili per gli OEM per le implementazioni di test.

Test CTS

Per eseguire i test CTS, consulta la sezione Esecuzione dei test CTS. Il CTS i test relativi a Jetpack WindowManager si trovano in cts/tests/framework/base/windowmanager/jetpack/. Il nome del modulo di test è CtsWindowManagerJetpackTestCases.

Test di WindowManager

Per scaricare i test di Jetpack WindowManager, segui le Istruzioni per Android Jetpack. I test si trovano nella libreria delle finestre sotto il modulo window:window: window/window/src/androidTest/.

Per eseguire i test del dispositivo per il modulo window:window dalla riga di comando: le seguenti:

  1. Collega un dispositivo con opzioni sviluppatore e debug USB attivato.
  2. Consenti al computer di eseguire il debug del dispositivo.
  3. Apri una shell nella directory principale del repository Androidx.
  4. Cambia directory in framework/support.
  5. Esegui questo comando: ./gradlew window:window:connectedAndroidTest.
  6. Analizza i risultati.

Per eseguire i test da Android Studio:

  1. Apri Android Studio.
  2. Collega un dispositivo con opzioni sviluppatore e debug USB attivato.
  3. Consenti al computer di eseguire il debug del dispositivo.
  4. Vai a un test nella libreria delle finestre del modulo della finestra.
  5. Apri una classe di test ed esegui utilizzando le frecce verdi sul lato destro del dell'editor.

In alternativa, puoi creare una configurazione in Android Studio per eseguire un test di valutazione, una classe di test o tutti i test di un modulo.

I risultati possono essere analizzati manualmente osservando l'output della shell. Alcune vengono ignorati se il dispositivo non soddisfa determinate ipotesi. I risultati sono salvate in una posizione standard e gli analisti possono scrivere uno script per automatizzare dei risultati.