Die Jetpack WindowManager- Bibliothek ermöglicht Anwendungsentwicklern die Unterstützung neuer Geräteformfaktoren und Umgebungen mit mehreren Fenstern.
WindowManager Extensions (Extensions) ist ein optionales Android-Plattformmodul, das eine Vielzahl von Jetpack WindowManager-Funktionen ermöglicht. Das Modul ist in AOSP in frameworks/base/libs/WindowManager/Jetpack
implementiert und wird auf Geräten ausgeliefert, die die WindowManager-Funktionen unterstützen.
Verteilung des Erweiterungsmoduls
Erweiterungen werden in eine .jar
Bibliothek kompiliert und in der system_ext
Partition auf einem Gerät abgelegt, wenn Erweiterungen im Geräte-Makefile aktiviert sind.
Um Erweiterungen auf einem Gerät zu aktivieren, fügen Sie Folgendes zum Makefile des Produktgeräts hinzu:
$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)
Dadurch werden die Pakete androidx.window.extensions
und androidx.window.sidecar
auf dem Gerät aktiviert und die Eigenschaft persist.wm.extensions.enabled
festgelegt. Durch das Einschließen dieser Pakete in das Makefile werden auch Deklarationen in etc/permissions/
platziert, sodass sie für Anwendungsprozesse verfügbar sind. Normalerweise werden die Module zur Laufzeit als Teil des Anwendungsprozesses geladen und ausgeführt, wenn sie von der Jetpack WindowManager-Bibliothek verwendet werden, wodurch ihre Funktionsweise dem clientseitigen Framework-Code ähnelt, wie in der folgenden Abbildung dargestellt:
Das Modul androidx.window.extensions
ist das aktuelle Erweiterungsmodul, das sich in der aktiven Entwicklung befindet. Das androidx.window.sidecar
-Modul ist ein Legacy-Modul, das aus Kompatibilitätsgründen mit den frühesten Versionen von Jetpack WindowManager enthalten ist, aber das Sidecar wird nicht mehr aktiv gepflegt.
Die folgende Abbildung zeigt die Logik zur Bestimmung der Verwendung von androidx.window.extensions
oder androidx.window.sidecar
.
Erweiterungsmodule
Erweiterungen bieten Fensterfunktionen für faltbare Geräte mit großem Bildschirm und Geräte, die Fenster auf externen Displays unterstützen. Zu den Funktionsbereichen gehören:
OEM-Implementierungen von Erweiterungen können Nullkomponenten oder Komponenten mit Standard- oder Stub-Implementierungen der Methoden in der WindowExtensions
Schnittstelle bereitstellen, wenn die Gerätehardware die entsprechenden Funktionen nicht unterstützt, es sei denn, die Funktion wird ausdrücklich im Compatibility Definition Document (CDD) 7.1.1.1 angefordert .
Erweiterungen und Jetpack-APIs
Das WindowManager Extensions-Modul stellt zusätzlich zu den öffentlichen Plattform-APIs eine eigene API-Oberfläche bereit. Das Erweiterungsmodul wird öffentlich in einer nicht für Entwickler zugänglichen Jetpack-Bibliothek „ androidx.window.extensions
entwickelt, sodass Jetpack WindowManager ( androidx.window
) zur Kompilierungszeit eine Verknüpfung damit herstellen kann. Die Erweiterungs-API-Oberfläche stellt normalerweise APIs auf niedrigerer Ebene bereit.
Die von den Erweiterungen bereitgestellten APIs sind nur für die Verwendung durch die Jetpack WindowManager-Bibliothek vorgesehen. Die Erweiterungs-APIs sind nicht dafür gedacht, direkt von Anwendungsentwicklern aufgerufen zu werden. Die Erweiterungsbibliothek darf nicht als Abhängigkeit für eine Anwendung in der Gradle-Build-Datei hinzugefügt werden, um die korrekte Funktionalität sicherzustellen. Vermeiden Sie es, die Erweiterungsbibliothek direkt vorab in eine Anwendung zu kompilieren; Verlassen Sie sich stattdessen auf das Laden zur Laufzeit, um zu verhindern, dass eine Mischung aus vorkompilierten und zur Laufzeit bereitgestellten Erweiterungsklassen geladen wird.
Jetpack WindowManager ( androidx.window
) soll als Anwendungsabhängigkeit hinzugefügt werden und stellt die öffentlichen APIs für Entwickler bereit, einschließlich derjenigen für WindowManager-Erweiterungsfunktionen. Die WindowManager-Bibliothek lädt Erweiterungen automatisch in den Anwendungsprozess und verpackt die Erweiterungs-APIs auf niedrigerer Ebene in Abstraktionen auf höherer Ebene und fokussiertere Schnittstellen. Die WindowManager Jetpack-APIs folgen den Standards der modernen Android-Anwendungsentwicklung und sollen eine bequeme Interoperabilität bieten, indem sie sich gut in Codebasen integrieren lassen, die andere AndroidX-Bibliotheken verwenden.
Erweiterungsversionen und Updates
Das Erweiterungsmodul kann zusammen mit den jährlichen oder vierteljährlichen Updates der Android-Plattform aktualisiert werden. Vierteljährliche Updates ermöglichen die Erhöhung des Erweiterungs-API-Levels zwischen den API-Updates der Android-Plattform, was eine schnellere Iteration ermöglicht und OEMs die Möglichkeit bietet, kurz vor der Markteinführung der Hardware offiziellen API-Zugriff auf neue Funktionen hinzuzufügen.
In der folgenden Tabelle sind die androidx.window.extensions
API-Versionen für verschiedene Android-Versionen aufgeführt.
Android-Plattformversion | API-Ebene der WindowManager-Erweiterungen | androidx.window.extensions API-Version |
---|---|---|
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 |
Die Erweiterungs-API-Ebene (mittlere Spalte) wird jedes Mal erhöht, wenn eine Ergänzung zur vorhandenen stabilen API-Oberfläche (rechte Spalte) erfolgt.
Abwärts- und Vorwärtskompatibilität
Jetpack WindowManager bewältigt die Komplexität des Umgangs mit häufigen Aktualisierungen auf API-Ebene, schneller API-Entwicklung und Abwärtskompatibilität. Wenn der Bibliothekscode im Anwendungsprozess ausgeführt wird, überprüft die Bibliothek die deklarierte Erweiterungs-API-Ebene und gewährt Zugriff auf Funktionen entsprechend der deklarierten Ebene.
Um eine Anwendung vor einem Absturz zur Laufzeit zu schützen, führt WindowManager außerdem eine Laufzeit-Java-Reflektionsprüfung der verfügbaren Erweiterungs-APIs entsprechend der deklarierten Erweiterungs-API-Ebene durch. Bei einer Nichtübereinstimmung kann WindowManager die Verwendung von Erweiterungen (teilweise oder vollständig) deaktivieren und die relevanten Funktionen als für die Anwendung nicht verfügbar melden.
WindowManager-Erweiterungen werden als system_ext
Modul implementiert, das private Plattform-APIs verwendet, um bei der Implementierung der Erweiterungsfunktionen den WindowManager-Kern, DeviceStateManager
und andere Systemdienste aufzurufen.
Die Kompatibilität mit Vorabversionen von Erweiterungen vor der entsprechenden vierteljährlichen oder jährlichen Android-Plattformversion, mit der die Versionen finalisiert werden, kann möglicherweise nicht aufrechterhalten werden. Der vollständige Verlauf der Erweiterungs-APIs finden Sie in den Textdateien des Release-Zweigs window:extensions:extensions
API .
Neuere Versionen von Erweiterungen müssen weiterhin mit älteren Versionen von WindowManager funktionieren, die in Anwendungen kompiliert wurden, um die Aufwärtskompatibilität aufrechtzuerhalten. Um dies sicherzustellen, fügt jede neue Version der Erweiterungs-API nur neue APIs hinzu und entfernt keine älteren. Dadurch können Anwendungen mit älteren WindowManager-Versionen weiterhin die älteren Erweiterungs-APIs verwenden, mit denen die Apps kompiliert wurden.
Die CTS-Überprüfung stellt sicher, dass für jede deklarierte Version der Erweiterungs-APIs auf dem Gerät alle APIs für diese und frühere Versionen vorhanden und funktionsfähig sind.
Leistung
Das Erweiterungsmodul wird ab Android 14 (API-Level 34) standardmäßig in Nicht-Bootclasspath-Systemklassenladern zwischengespeichert, sodass es keine Auswirkungen auf die Leistung durch das Laden des Moduls in den Speicher beim App-Start gibt. Die Verwendung einzelner Modulfunktionen kann einen geringfügigen Einfluss auf die Leistungseigenschaften von Apps haben, wenn zusätzliche IPC-Aufrufe zwischen dem Client und dem Server durchgeführt werden.
Module
Einbettung von Aktivitäten
Die Aktivitätseinbettungskomponente stellt eine Reihe von Funktionen bereit, die es Anwendungen ermöglichen, die Präsentation von Aktivitätsfenstern innerhalb der Grenzen der übergeordneten Anwendung zu organisieren. Dazu gehört die gleichzeitige Anzeige zweier Aktivitäten nebeneinander in einem Mehrfenster-Layout, was die Optimierung großer Bildschirme für ältere Anwendungen erleichtert.
Die Aktivitätseinbettungskomponente muss auf allen Geräten verfügbar sein, die über ein integriertes Display mit einer Größe von mindestens sw600 dp
verfügen. Das Einbetten von Aktivitäten muss auch auf Geräten aktiviert sein, die externe Anzeigeverbindungen unterstützen, da die Anwendung möglicherweise in größerer Größe angezeigt wird, wenn externe Anzeigegeräte zur Laufzeit angeschlossen werden.
Gerätekonfiguration
Es ist keine spezielle Gerätekonfiguration erforderlich, außer der Aktivierung des Erweiterungsmoduls, wie im Abschnitt „Verteilung des Erweiterungsmoduls“ beschrieben. Es ist sinnvoll, Erweiterungen auf allen Geräten zu aktivieren, die den Mehrfenstermodus unterstützen. Zukünftige Android-Versionen werden wahrscheinlich Erweiterungen für gängige Handheld- und Großbildschirm-Gerätekonfigurationen erforderlich machen.
Informationen zum Fensterlayout
Die Fensterlayout-Informationskomponente identifiziert die Position und den Zustand des Scharniers auf einem faltbaren Gerät, wenn das Scharnier ein Anwendungsfenster kreuzt. Informationen zum Fensterlayout ermöglichen es Anwendungen, auf faltbare Geräte zu reagieren und optimierte Layouts im Tischmodus anzuzeigen. Einzelheiten zur Nutzung finden Sie unter Machen Sie Ihre App Fold-fähig .
Faltbare Android-Geräte, die über ein Scharnier verfügen, das separate oder durchgehende Anzeigefeldbereiche verbindet, müssen die Informationen über das Scharnier Anwendungen über WindowLayoutComponent
zur Verfügung stellen.
Die Scharnierposition und -grenzen müssen relativ zum Anwendungsfenster gemeldet werden, das durch einen an die API übergebenen Context
identifiziert wird. Wenn sich die Grenzen des Anwendungsfensters nicht mit den Scharniergrenzen überschneiden, darf das DisplayFeature
des Scharniers nicht gemeldet werden. Es ist auch akzeptabel, die Anzeigefunktionen nicht zu melden, wenn ihre Position möglicherweise nicht zuverlässig gemeldet wird, beispielsweise wenn ein Anwendungsfenster vom Benutzer im Mehrfenstermodus oder im Kompatibilitäts-Letterbox-Modus frei verschoben werden kann.
Bei Faltfunktionen müssen die Zustandsaktualisierungen gemeldet werden, wenn sich die Scharnierposition zwischen den stabilen Zuständen ändert. Standardmäßig muss die API in einem flachen Anzeigezustand FoldingFeature.State.FLAT
melden. Wenn die Gerätehardware in einem stabilen Zustand im halb gefalteten Modus belassen werden kann, muss die API FoldingFeature.State.HALF_OPENED
melden. In der API gibt es keinen geschlossenen Zustand, da das Anwendungsfenster in einem solchen Fall entweder nicht sichtbar wäre oder die Scharniergrenzen nicht überschreiten würde.
Gerätekonfiguration
Um die Implementierung der Faltfunktion zu unterstützen, müssen OEMs Folgendes tun:
Konfigurieren Sie die Gerätezustände in
device_state_configuration.xml
, die vonDeviceStateManagerService
verwendet werden sollen. SieheDeviceStateProviderImpl.java
als Referenz.Wenn die Standardimplementierungen von
DeviceStateProvider
oderDeviceStatePolicy
nicht für das Gerät geeignet sind, kann eine benutzerdefinierte Implementierung verwendet werden.Aktivieren Sie das Modul „Erweiterungen“, wie im Abschnitt „Verteilung des Erweiterungsmoduls“ beschrieben.
Geben Sie den Speicherort der Anzeigefunktionen in der Zeichenfolgenressource
com.android.internal.R.string.config_display_features
an (normalerweise inframeworks/base/core/res/res/values/config.xml
im Geräte-Overlay).Das erwartete Format für die Zeichenfolge ist:
<type>-[<left>,<top>,<right>,<bottom>]
Der
type
kann entwederfold
oderhinge
sein. Die Werte fürleft
,top
,right
undbottom
sind ganzzahlige Pixelkoordinaten im Anzeigekoordinatenraum in der natürlichen Anzeigeausrichtung. Die Konfigurationszeichenfolge kann mehrere durch Semikolons getrennte Anzeigefunktionen enthalten.Zum Beispiel:
<!-- Jetpack WindowManager display features --> <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
Definieren Sie die Zuordnung zwischen den internen Gerätestatus-IDs, die in
DeviceStateManager
verwendet werden, und den öffentlichen Statuskonstanten, die incom.android.internal.R.array.config_device_state_postures
an Entwickler gesendet werden.Das erwartete Format für jeden Eintrag ist:
<device_specific_state_identifier>:<Jetpack WindowManager state identifier>
Die unterstützten Statuskennungen sind:
-
COMMON_STATE_NO_FOLDING_FEATURES = 1
: Der Staat verfügt über keine zu meldenden Faltfunktionen. Beispielsweise kann es sich um den geschlossenen Zustand des typischen Klappgeräts mit dem Hauptbildschirm auf der Innenseite handeln. -
COMMON_STATE_HALF_OPENED = 2
: Die Faltfunktion ist halb geöffnet. -
COMMON_STATE_FLAT = 3
: Die Faltfunktion ist flach. Beispielsweise kann es sich um den geöffneten Zustand eines typischen Klappgeräts mit dem Hauptbildschirm auf der Innenseite handeln. -
COMMON_STATE_USE_BASE_STATE = 1000
: In Android 14 ein Wert, der für emulierte Zustände verwendet werden kann, bei denen der Scharnierzustand mithilfe des Basiszustands abgeleitet wird, wie inCommonFoldingFeature.java
definiert
Weitere Informationen finden Sie unter
DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int)
.Zum Beispiel:
<!-- 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>
-
Fensterbereich
Die Fensterbereichskomponente bietet eine Reihe von Funktionen, die Anwendungen Zugriff auf zusätzliche Displays und Anzeigebereiche auf einigen faltbaren Geräten und Geräten mit mehreren Displays ermöglichen.
Der hintere Anzeigemodus ermöglicht es einer Anwendung, die Kameravorschau-Benutzeroberfläche auf dem Cover-Display eines faltbaren Geräts anzuzeigen, um die Verwendung der Hauptkamera des Geräts für Selfies und Videos zu ermöglichen. Geräte, die über ein Android-kompatibles (wie im Android CDD in Bezug auf Attribute wie Größe, Dichte und verfügbare Navigationsfunktionen definiertes) Cover-Display verfügen, das mit den hinteren Gerätekameras übereinstimmt, müssen Zugriff auf den hinteren Anzeigemodus ermöglichen.
Unter Android 14 ermöglicht der Dual-Display-Modus Anwendungen, die auf dem Innendisplay eines faltbaren Geräts ausgeführt werden, zusätzliche Inhalte auf dem Cover-Display für andere Benutzer anzuzeigen; Beispielsweise kann das Cover-Display der fotografierten oder aufgenommenen Person die Kameravorschau anzeigen.
Gerätekonfiguration
Um die Implementierung der Faltfunktion zu unterstützen, müssen OEMs Folgendes tun:
Konfigurieren Sie die Gerätezustände in
device_state_configuration.xml
, die vonDeviceStateManagerService
verwendet werden sollen. Weitere Informationen finden Sie unterDeviceStateProviderImpl.java
.Wenn die Standardimplementierung von
DeviceStateProvider
oderDeviceStatePolicy
nicht für das Gerät geeignet ist, kann eine benutzerdefinierte Implementierung verwendet werden.Geben Sie für faltbare Geräte, die den offenen oder flachen Modus unterstützen, die entsprechenden Statuskennungen in
com.android.internal.R.array.config_openDeviceStates
an.Für einklappbare Geräte, die gefaltete Zustände unterstützen, listen Sie die entsprechenden Zustandskennungen in
com.android.internal.R.array.config_foldedDeviceStates
auf.Für einklappbare Geräte, die einen halb zusammengeklappten Zustand unterstützen (Scharnier ist halb geöffnet wie bei einem Laptop), listen Sie die entsprechenden Zustände in
com.android.internal.R.array.config_halfFoldedDeviceStates
auf.Für Geräte, die den hinteren Anzeigemodus unterstützen:
- Listen Sie die entsprechenden Zustände in
com.android.internal.R.array.config_rearDisplayDeviceStates
fürDeviceStateManager
auf. - Geben Sie die physische Anzeigeadresse des hinteren Displays in
com.android.internal.R.string.config_rearDisplayPhysicalAddress
an. - Geben Sie die Statuskennung in
com.android.internal.R.integer.config_deviceStateRearDisplay
an, die von Erweiterungen verwendet werden soll. - Fügen Sie die Statuskennung in
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests
hinzu, um sie für Anwendungen verfügbar zu machen.
- Listen Sie die entsprechenden Zustände in
Unter Android 14 für Geräte, die den dualen (gleichzeitigen) Anzeigemodus unterstützen:
- Setzen Sie
com.android.internal.R.bool.config_supportsConcurrentInternalDisplays
auftrue
. - Geben Sie die physische Anzeigeadresse des hinteren Displays in
com.android.internal.R.config_deviceStateConcurrentRearDisplay
an. - Geben Sie den Statusbezeichner in
com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay
an, der von Erweiterungen verwendet werden soll, wenn der Bezeichner für Anwendungen verfügbar gemacht werden soll. - Fügen Sie die Statuskennung in
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests
hinzu, um sie für Anwendungen verfügbar zu machen.
- Setzen Sie
Überprüfung
OEMs müssen ihre Implementierungen überprüfen, um das erwartete Verhalten in gängigen Szenarien sicherzustellen. CTS-Tests und Tests mit Jetpack WindowManager stehen OEMs zum Testen von Implementierungen zur Verfügung.
CTS-Tests
Informationen zum Ausführen der CTS-Tests finden Sie unter Ausführen von CTS-Tests . Die CTS-Tests im Zusammenhang mit Jetpack WindowManager finden Sie unter cts/tests/framework/base/windowmanager/jetpack/
. Der Name des Testmoduls lautet CtsWindowManagerJetpackTestCases
.
WindowManager-Tests
Um die Jetpack WindowManager-Tests herunterzuladen, befolgen Sie die Android Jetpack-Anweisungen . Die Tests befinden sich in der Fensterbibliothek unter dem Modul window:window
window/window/src/androidTest/
.
Gehen Sie wie folgt vor, um die Gerätetests für das Modul window:window
über die Befehlszeile auszuführen:
- Schließen Sie ein Gerät an, auf dem Entwickleroptionen und USB-Debugging aktiviert sind.
- Erlauben Sie dem Computer, das Gerät zu debuggen.
- Öffnen Sie eine Shell im Stammverzeichnis des Androidx-Repositorys.
- Wechseln Sie in das Verzeichnis
framework/support
. - Führen Sie den folgenden Befehl aus:
./gradlew window:window:connectedAndroidTest
. - Analysieren Sie die Ergebnisse.
Gehen Sie wie folgt vor, um die Tests in Android Studio auszuführen:
- Öffnen Sie Android Studio.
- Schließen Sie ein Gerät an, auf dem Entwickleroptionen und USB-Debugging aktiviert sind.
- Erlauben Sie dem Computer, das Gerät zu debuggen.
- Navigieren Sie zu einem Test in der Fensterbibliothek des Fenstermoduls.
- Öffnen Sie eine Testklasse und führen Sie sie mithilfe der grünen Pfeile auf der rechten Seite des Editors aus.
Alternativ können Sie in Android Studio eine Konfiguration erstellen, um eine Testmethode, eine Testklasse oder alle Tests in einem Modul auszuführen.
Die Ergebnisse können manuell analysiert werden, indem man sich die Ausgabe der Shell ansieht. Einige Tests werden übersprungen, wenn das Gerät bestimmte Annahmen nicht erfüllt. Die Ergebnisse werden an einem Standardspeicherort gespeichert und Analysten können ein Skript schreiben, um die Analyse der Ergebnisse zu automatisieren.