Estensioni WindowManager

La libreria Jetpack WindowManager consente agli sviluppatori di applicazioni di supportare nuovi fattori di forma dei dispositivi e ambienti multifinestra.

WindowManager Extensions (Extensions) è un modulo della piattaforma Android opt-in che abilita una varietà di funzionalità WindowManager di Jetpack. Il modulo è implementato in AOSP in frameworks/base/libs/WindowManager/Jetpack e fornito su dispositivi che supportano le funzionalità WindowManager.

Distribuzione dei moduli estensioni

Le estensioni vengono compilate in una libreria .jar e inserite nella partizione system_ext su un dispositivo se le estensioni sono abilitate nel makefile del dispositivo.

Per abilitare le estensioni su un dispositivo, aggiungi quanto segue al makefile del dispositivo del prodotto:

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

Ciò abilita i pacchetti androidx.window.extensions e androidx.window.sidecar sul dispositivo e imposta la proprietà persist.wm.extensions.enabled . Includendo questi pacchetti nel makefile si inseriscono anche le dichiarazioni in etc/permissions/ , rendendole disponibili ai processi dell'applicazione. Normalmente i moduli vengono caricati ed eseguiti come parte del processo applicativo in fase di runtime quando utilizzati dalla libreria Jetpack WindowManager, che rende il suo funzionamento simile al codice framework lato client, come mostrato nella figura seguente:

Figura 1. Estensioni WindowManager caricate nel processo di applicazione in modo simile al codice della piattaforma.

Il modulo androidx.window.extensions è l'attuale modulo Estensioni in fase di sviluppo attivo. Il modulo androidx.window.sidecar è un modulo legacy incluso per compatibilità con le prime versioni di Jetpack WindowManager, ma il sidecar non viene più mantenuto 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 estensioni

Le estensioni forniscono funzionalità di finestra per dispositivi pieghevoli con schermo di grandi dimensioni e dispositivi che supportano la finestra su schermi esterni. Le aree di funzionalità includono:

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

Estensioni e API Jetpack

Il modulo WindowManager Extensions fornisce la propria superficie API oltre alle API della piattaforma pubblica. Il modulo Extensions è sviluppato pubblicamente in una libreria Jetpack androidx.window.extensions non rivolta agli sviluppatori, in modo che Jetpack WindowManager ( androidx.window ) possa collegarsi ad esso in fase di compilazione. La superficie dell'API Estensioni fornisce in genere API di livello inferiore.

Le API fornite dalle estensioni devono essere utilizzate solo dalla libreria WindowManager Jetpack. Le API delle estensioni non devono essere chiamate direttamente dagli sviluppatori di applicazioni. La libreria Extensions non deve essere aggiunta come dipendenza per un'applicazione nel file di build Gradle per garantire la corretta funzionalità. Evitare di precompilare la libreria delle estensioni direttamente in un'applicazione; fare affidamento invece sul caricamento in fase di esecuzione per evitare il caso di caricamento di una combinazione di classi di estensioni precompilate e fornite in fase di esecuzione.

Jetpack WindowManager ( androidx.window ) è pensato per essere aggiunto come dipendenza dell'applicazione e fornisce le API pubbliche rivolte agli sviluppatori, comprese quelle per le funzionalità delle estensioni WindowManager. La libreria WindowManager carica automaticamente le estensioni nel processo di applicazione e racchiude le API delle estensioni di livello inferiore in astrazioni di livello superiore e interfacce più mirate. Le API WindowManager Jetpack seguono gli standard dello sviluppo di applicazioni Android moderne e sono pensate per fornire una comoda interoperabilità integrandosi bene con le codebase che utilizzano altre librerie AndroidX.

Versioni e aggiornamenti delle estensioni

Il modulo Estensioni può essere aggiornato insieme agli aggiornamenti annuali o trimestrali della piattaforma Android. Gli aggiornamenti trimestrali consentono di aumentare il livello dell'API Extensions tra gli aggiornamenti API della piattaforma Android, consentendo un'iterazione più rapida e offrendo agli OEM l'opportunità di aggiungere l'accesso API ufficiale a nuove funzionalità in prossimità del lancio dell'hardware.

La tabella seguente elenca le versioni dell'API androidx.window.extensions per varie versioni di Android.

Versione della piattaforma Android Livello API delle estensioni WindowManager Versione dell'API androidx.window.extensions
Androide 14 3 1.2.0
Android 13QPR3 2 1.1.0
Androide 13 1 1.0.0
Android 12L 1 1.0.0

Il livello dell'API Estensioni (colonna centrale) viene aumentato ogni volta che viene aggiunta un'aggiunta alla superficie API stabile esistente (colonna di destra).

Compatibilità con le versioni precedenti e successive

Jetpack WindowManager gestisce la complessità di gestire frequenti aggiornamenti del livello API, rapida evoluzione delle API e compatibilità con le versioni precedenti. Quando il codice della libreria viene eseguito nel processo di richiesta, la libreria controlla il livello API delle estensioni dichiarato e fornisce l'accesso alle funzionalità in base al livello dichiarato.

Per proteggere un'applicazione da arresti anomali in fase di esecuzione, WindowManager esegue anche un controllo di riflessione Java in fase di esecuzione delle API delle estensioni disponibili in base al livello API delle estensioni dichiarato. Se c'è una mancata corrispondenza, WindowManager può disabilitare l'uso delle estensioni (parzialmente o completamente) e segnalare le funzionalità rilevanti come non disponibili per l'applicazione.

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

La compatibilità potrebbe non essere mantenuta con le versioni pre-release delle estensioni precedenti al corrispondente rilascio trimestrale o annuale della piattaforma Android con cui le versioni vengono finalizzate. La cronologia completa delle API delle estensioni è disponibile nel ramo di rilascio window:extensions:extensions API text files .

Le versioni più recenti di Extensions devono continuare a funzionare con le versioni precedenti di WindowManager compilate nelle applicazioni per mantenere la compatibilità futura. Per garantire ciò, qualsiasi nuova versione dell'API Extensions aggiunge solo nuove API e non rimuove quelle precedenti. Di conseguenza, le applicazioni con versioni precedenti di WindowManager possono continuare a utilizzare le API di estensioni precedenti su cui sono state compilate le app.

La verifica CTS garantisce che per qualsiasi versione dichiarata delle API delle estensioni sul dispositivo, tutte le API per quella versione e quelle precedenti siano presenti e funzionanti.

Prestazione

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

Moduli

Incorporamento di attività

Il componente di incorporamento delle attività fornisce una serie di funzionalità che consentono alle applicazioni di organizzare la presentazione della finestra delle attività entro i limiti dell'applicazione principale. Ciò include la visualizzazione simultanea di due attività affiancate in un layout a più riquadri, facilitando l'ottimizzazione dello schermo di grandi dimensioni per le applicazioni legacy.

Il componente di incorporamento delle attività deve essere disponibile su tutti i dispositivi dotati di display integrato di dimensioni pari o superiori a sw600 dp . L'incorporamento delle attività deve essere abilitato anche sui dispositivi che supportano le connessioni di display esterni, poiché l'applicazione potrebbe essere visualizzata in dimensioni maggiori quando i display esterni sono collegati in fase di runtime.

Configurazione del dispositivo

Non è necessaria alcuna configurazione specifica del dispositivo oltre all'abilitazione del modulo Estensioni come descritto nella sezione Distribuzione del modulo Estensioni . È opportuno abilitare le estensioni su tutti i dispositivi che supportano la modalità multifinestra. È probabile che le future versioni di Android rendano necessarie estensioni sulle comuni configurazioni di dispositivi portatili e con schermo di grandi dimensioni.

Informazioni sulla disposizione delle finestre

Il componente informativo sul layout della finestra identifica la posizione e lo stato del cardine su un dispositivo pieghevole quando il cardine attraversa una finestra dell'applicazione. Le informazioni sul layout delle finestre consentono alle applicazioni di rispondere e mostrare layout ottimizzati in modalità da tavolo sui dispositivi pieghevoli. Vedi Rendere la tua app pieghevole consapevole per i dettagli sull'utilizzo.

I dispositivi Android pieghevoli che includono una cerniera che collega aree del pannello di visualizzazione separate o continue devono rendere disponibili le informazioni sulla cerniera alle applicazioni tramite WindowLayoutComponent .

La posizione cardine e i limiti devono essere riportati rispetto alla finestra dell'applicazione identificata da un Context passato all'API. Se i limiti della finestra dell'applicazione non si intersecano con i limiti del cardine, la DisplayFeature del cardine non deve essere segnalata. È inoltre accettabile non segnalare le caratteristiche di visualizzazione quando la loro posizione potrebbe non essere segnalata in modo affidabile, ad esempio quando la finestra di un'applicazione può essere spostata liberamente dall'utente in modalità multifinestra o in modalità letterboxing di compatibilità.

Per le funzionalità di piegatura , gli aggiornamenti di stato devono essere segnalati quando la posizione della cerniera cambia tra gli stati stabili. Per impostazione predefinita, in uno stato di visualizzazione flat, l'API deve segnalare FoldingFeature.State.FLAT . Se l'hardware del dispositivo può essere lasciato in modalità piegata a metà in uno stato stabile, l'API deve segnalare FoldingFeature.State.HALF_OPENED . Non esiste uno stato chiuso nell'API, poiché in tal caso la finestra dell'applicazione non sarebbe visibile o non oltrepasserebbe i limiti dei cardini.

Configurazione del dispositivo

Per supportare l'implementazione della funzionalità di piegatura, gli OEM devono effettuare le seguenti operazioni:

  • Configurare gli stati del dispositivo in device_state_configuration.xml affinché vengano utilizzati da DeviceStateManagerService . Vedi DeviceStateProviderImpl.java come riferimento.

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

  • Abilita il modulo Estensioni come descritto nella sezione Distribuzione del modulo Estensioni .

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

    Il formato previsto per la stringa è:

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

    Il type può essere fold o hinge . I valori per left , top , right e bottom sono coordinate di pixel intere nello spazio delle coordinate di visualizzazione nell'orientamento naturale dello schermo. La stringa di configurazione può contenere più funzionalità di visualizzazione separate da punto e virgola.

    Per esempio:

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

  • Definire la mappatura tra gli identificatori di stato del dispositivo interno utilizzati in DeviceStateManager e le costanti di stato pubbliche inviate agli sviluppatori in com.android.internal.R.array.config_device_state_postures .

    Il formato previsto per ciascuna 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 caratteristiche di piegatura da segnalare. Ad esempio, può essere lo stato chiuso del tipico dispositivo di piegatura con lo schermo principale sul lato interno.
    • COMMON_STATE_HALF_OPENED = 2 : la funzione di piegatura è semiaperta.
    • COMMON_STATE_FLAT = 3 : la funzione di piegatura è piatta. Ad esempio, può essere lo stato aperto del tipico dispositivo di piegatura con lo schermo principale sul lato interno.
    • COMMON_STATE_USE_BASE_STATE = 1000 : in Android 14, un valore che può essere utilizzato per gli stati emulati in cui lo stato cerniera viene derivato utilizzando lo stato di base, come definito in CommonFoldingFeature.java

    Per ulteriori informazioni, vedere DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int) .

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

Zona finestra

Il componente area finestra fornisce una serie di funzionalità che consentono alle applicazioni di accedere a display e aree di visualizzazione aggiuntivi su alcuni dispositivi pieghevoli e multischermo.

La modalità display posteriore consente a un'applicazione di mostrare l'interfaccia utente di anteprima della fotocamera sul display della cover di un dispositivo pieghevole per consentire l'uso della fotocamera del dispositivo principale per selfie e video. I dispositivi dotati di display compatibile con Android (come definito dal CDD di Android in termini di attributi quali dimensioni, densità e funzionalità di navigazione disponibili) che si allinea con le fotocamere posteriori del dispositivo devono fornire l'accesso alla modalità display posteriore.

Su Android 14, la modalità doppio display consente alle applicazioni eseguite sul display interno di un dispositivo pieghevole di mostrare contenuti aggiuntivi sul display della cover di fronte ad altri utenti; ad esempio, il display sulla copertina può mostrare l'anteprima della fotocamera alla persona che viene fotografata o registrata.

Configurazione del dispositivo

Per supportare l'implementazione della funzionalità di piegatura, gli OEM devono effettuare le seguenti operazioni:

  • Configurare gli stati del dispositivo in device_state_configuration.xml affinché vengano utilizzati da DeviceStateManagerService . Per ulteriori informazioni, vedere DeviceStateProviderImpl.java .

    Se l'implementazione predefinita di DeviceStateProvider o DeviceStatePolicy non è adatta al dispositivo, è possibile utilizzare un'implementazione personalizzata.

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

  • Per i dispositivi in-fold che supportano gli stati ripiegati, elenca gli identificatori di stato corrispondenti in com.android.internal.R.array.config_foldedDeviceStates .

  • Per i dispositivi ripiegati che supportano uno stato piegato a metà (la cerniera è aperta a metà come un laptop), elenca gli stati corrispondenti in com.android.internal.R.array.config_halfFoldedDeviceStates .

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

    • Elenca gli stati corrispondenti in com.android.internal.R.array.config_rearDisplayDeviceStates per DeviceStateManager .
    • Specificare l'indirizzo fisico del display posteriore in com.android.internal.R.string.config_rearDisplayPhysicalAddress .
    • Specificare l'identificatore di 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 .
    • Specificare l'indirizzo fisico del display posteriore in com.android.internal.R.config_deviceStateConcurrentRearDisplay .
    • Specificare l'identificatore di stato in com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay 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 proprie implementazioni per garantire il comportamento previsto negli scenari comuni. I test CTS e quelli che utilizzano Jetpack WindowManager sono disponibili per gli OEM per testare le implementazioni.

Prove CTS

Per eseguire i test CTS, consulta Eseguire i test CTS . I test CTS 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 Jetpack WindowManager, seguire le Istruzioni Jetpack Android . I test si trovano nella libreria della finestra sotto il modulo window:window window: window/window/src/androidTest/ .

Per eseguire i test del dispositivo per il window:window dalla riga di comando, procedi come segue:

  1. Collega un dispositivo con opzioni sviluppatore e debug USB abilitati.
  2. Consentire al computer di eseguire il debug del dispositivo.
  3. Apri una shell nella directory root del repository Androidx.
  4. Cambia la directory in framework/support .
  5. Esegui il comando seguente: ./gradlew window:window:connectedAndroidTest .
  6. Analizzare i risultati.

Per eseguire i test da Android Studio, procedi come segue:

  1. Apri AndroidStudio.
  2. Collega un dispositivo con opzioni sviluppatore e debug USB abilitati.
  3. Consentire al computer di eseguire il debug del dispositivo.
  4. Passare a un test all'interno della libreria di finestre del modulo finestra.
  5. Apri una lezione di prova ed eseguila utilizzando le frecce verdi sul lato destro dell'editor.

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

I risultati possono essere analizzati manualmente osservando l'output della shell. Alcuni test vengono saltati se il dispositivo non soddisfa determinati presupposti. I risultati vengono salvati in una posizione standard e gli analisti possono scrivere uno script per automatizzare l'analisi dei risultati.