WindowManager-Erweiterungen

Mit der Jetpack WindowManager-Bibliothek können App-Entwickler neue Geräteformfaktoren und Multi-Window-Umgebungen unterstützen.

WindowManager Extensions (Extensions) ist ein optionales Android-Plattformmodul, das verschiedene Jetpack WindowManager-Funktionen ermöglicht. Das Modul wird in AOSP in frameworks/base/libs/WindowManager/Jetpack implementiert und auf Geräten ausgeliefert, die die WindowManager-Funktionen unterstützen.

Verteilung von Erweiterungsmodulen

Erweiterungen werden in einer .jar-Bibliothek kompiliert und in der system_ext-Partition auf einem Gerät platziert, wenn Erweiterungen im Make-File des Geräts aktiviert sind.

Wenn Sie Erweiterungen auf einem Gerät aktivieren möchten, fügen Sie der Produktgeräte-Makefile Folgendes 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 wird festgelegt. Wenn Sie diese Pakete in die Make-Datei einfügen, werden auch Deklarationen in etc/permissions/ platziert, sodass sie für Anwendungsprozesse verfügbar sind. Normalerweise werden die Module zur Laufzeit in den Anwendungsprozess geladen und als Teil davon ausgeführt, wenn sie von der Jetpack WindowManager-Bibliothek verwendet werden. Dadurch ähnelt ihre Funktionsweise dem clientseitigen Framework-Code, 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 altes Modul, das zur Kompatibilität mit den ersten Versionen von Jetpack WindowManager enthalten ist. Die Sidecar-Funktion wird jedoch nicht mehr aktiv gewartet.

Die folgende Abbildung zeigt die Logik für die Entscheidung, ob androidx.window.extensions oder androidx.window.sidecar verwendet werden soll.

Erweiterungsmodule

Erweiterungen bieten Fensterfunktionen für faltbare Geräte mit großem Display und Geräte, die Fensterfunktionen auf externen Displays unterstützen. Die Funktionsbereiche umfassen:

• Aktivitätseinbettung
• Informationen zum Fensterlayout
• Fensterbereich

OEM-Implementierungen von Erweiterungen können Null-Komponenten 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 bietet neben den öffentlichen Plattform-APIs eine eigene API-Oberfläche. Das Extensions-Modul wird öffentlich in einer androidx.window.extensions-Jetpack-Bibliothek entwickelt, die nicht für Entwickler bestimmt ist. So kann Jetpack WindowManager (androidx.window) zur Kompilierzeit darauf verweisen. Die Extensions API-Oberfläche bietet in der Regel APIs auf niedrigerer Ebene.

Die von Erweiterungen bereitgestellten APIs sind nur für die Verwendung durch die Jetpack WindowManager-Bibliothek vorgesehen. Die Extensions APIs sind nicht dafür vorgesehen, direkt von Anwendungsentwicklern aufgerufen zu werden. Die Extensions-Bibliothek darf nicht als Abhängigkeit für eine Anwendung in der Gradle-Build-Datei hinzugefügt werden, um eine korrekte Funktionalität zu gewährleisten. Vermeiden Sie es, die Extensions-Bibliothek direkt in eine Anwendung zu vorkompilieren. Verwenden Sie stattdessen das Laufzeitladen, um zu verhindern, dass eine Mischung aus vorkompilierten und zur Laufzeit bereitgestellten Extensions-Klassen geladen wird.

Jetpack WindowManager (androidx.window) soll als Anwendungsabhängigkeit hinzugefügt werden und bietet die öffentlichen, entwicklerorientierten APIs, einschließlich der APIs für WindowManager Extensions-Funktionen. Die WindowManager-Bibliothek lädt Erweiterungen automatisch in den Anwendungsprozess und umschließt die Extensions APIs auf niedrigerer Ebene mit Abstraktionen auf höherer Ebene und fokussierteren Schnittstellen. Die WindowManager Jetpack APIs entsprechen den Standards der modernen Android-App-Entwicklung und sollen eine komfortable Interoperabilität ermöglichen, indem sie sich gut in Codebases integrieren lassen, in denen andere AndroidX-Bibliotheken verwendet werden.

Versionen und Updates von Erweiterungen

Das Extensions-Modul kann jährlich oder vierteljährlich zusammen mit der Android-Plattform aktualisiert werden. Durch vierteljährliche Updates kann das Extensions API-Level zwischen den Android-Plattform-API-Updates erhöht werden. Das ermöglicht schnellere Iterationen und bietet OEMs die Möglichkeit, neuen Funktionen kurz vor der Hardwareeinführung offiziellen API-Zugriff hinzuzufügen.

In der folgenden Tabelle sind die androidx.window.extensions-API-Versionen für verschiedene Android-Versionen aufgeführt.

Das Extensions API-Level (mittlere Spalte) wird jedes Mal erhöht, wenn die vorhandene stabile API-Oberfläche (rechte Spalte) erweitert wird.

Abwärts- und Vorwärtskompatibilität

Jetpack WindowManager kümmert sich um die Komplexität, die durch häufige API-Level-Updates, schnelle API-Entwicklung und Abwärtskompatibilität entsteht. Wenn der Bibliothekscode im Anwendungsprozess ausgeführt wird, prüft die Bibliothek die deklarierte Extensions API-Ebene und bietet Zugriff auf Funktionen entsprechend der deklarierten Ebene.

Um eine Anwendung vor Abstürzen zur Laufzeit zu schützen, führt WindowManager auch eine Java-Reflexionsprüfung der verfügbaren Extensions APIs gemäß der deklarierten Extensions API-Ebene durch. Bei einer Abweichung kann WindowManager die Verwendung von Erweiterungen (teilweise oder vollständig) deaktivieren und die entsprechenden Funktionen als für die Anwendung nicht verfügbar melden.

WindowManager-Erweiterungen werden als system_ext-Modul implementiert, das private Plattform-APIs verwendet, um WindowManager-Core, DeviceStateManager und andere Systemdienste in der Implementierung der Erweiterungsfunktionen aufzurufen.

Die Kompatibilität mit Vorabversionen von Erweiterungen vor der entsprechenden vierteljährlichen oder jährlichen Android-Plattformversion, mit der die Versionen abgeschlossen werden, wird möglicherweise nicht aufrechterhalten. Der vollständige Verlauf der Extensions APIs ist im Release-Branch window:extensions:extensions API-Textdateien verfügbar.

Neuere Versionen von Extensions müssen weiterhin mit älteren Versionen von WindowManager funktionieren, die in Anwendungen kompiliert wurden, um die Vorwärtskompatibilität aufrechtzuerhalten. Um dies zu gewährleisten, werden in jeder neuen Version der Extensions API nur neue APIs hinzugefügt und keine älteren entfernt. Daher können Anwendungen mit älteren WindowManager-Versionen weiterhin die älteren Extensions-APIs verwenden, für die die Apps kompiliert wurden.

Die CTS-Überprüfung stellt sicher, dass für jede deklarierte Version von Extensions APIs auf dem Gerät alle APIs für diese und frühere Versionen vorhanden sind und funktionieren.

Leistung

Das Extensions-Modul wird ab Android 14 (API-Level 34) standardmäßig in Systemklassen-Loadern, die nicht zum Boot-Classpath gehören, zwischengespeichert. Das Laden des Moduls in den Arbeitsspeicher beim Start der App hat also keine Auswirkungen auf die Leistung. Die Verwendung einzelner Modulfunktionen kann sich geringfügig auf die Leistungsmerkmale von Apps auswirken, wenn zusätzliche IPC-Aufrufe zwischen dem Client und dem Server ausgeführt werden.

Module

Einbettung von Aktivitäten

Mit der Komponente activity embedding können Anwendungen ihre Benutzeroberfläche für Geräte mit großen Bildschirmen und externe Displays optimieren. Durch das Einbetten von Aktivitäten können zwei Aktivitäten nebeneinander in einem Layout mit mehreren Bereichen dargestellt werden. So wird die adaptive App-Entwicklung für Legacy-Anwendungen erleichtert.

Die Komponente für die Einbettung von Aktivitäten muss auf allen Geräten mit einem integrierten Display verfügbar sein, das mindestens sw600dp groß ist. Die Einbettung von Aktivitäten muss auch auf Geräten aktiviert sein, die externe Displayverbindungen unterstützen, da die Anwendung möglicherweise in einer größeren Größe angezeigt wird, wenn externe Displays zur Laufzeit verbunden sind.

Gerätekonfiguration

Außer der Aktivierung des Moduls „Erweiterungen“ gemäß der Beschreibung im Abschnitt Verteilung des Moduls „Erweiterungen“ ist keine spezielle Gerätekonfiguration erforderlich. Es ist sinnvoll, Erweiterungen auf allen Geräten zu aktivieren, die den Multi-Window-Modus unterstützen. Bei zukünftigen Android-Versionen sind Erweiterungen wahrscheinlich für gängige Konfigurationen von Handheld-Geräten und Geräten mit großem Display erforderlich.

Informationen zum Fensterlayout

Die Komponente für Informationen zum Fensterlayout gibt die Position und den Status des Scharniers auf einem faltbaren Gerät an, wenn das Scharnier ein Anwendungsfenster kreuzt. Informationen zum Fensterlayout ermöglichen es Anwendungen, auf den „Auf dem Tisch“-Modus auf faltbaren Geräten zu reagieren und optimierte Layouts anzuzeigen. Weitere Informationen zur Verwendung finden Sie unter App für faltbare Geräte optimieren.

Bei faltbaren Android-Geräten mit einem Scharnier, das separate oder durchgehende Displaybereiche verbindet, müssen die Informationen zum Scharnier über WindowLayoutComponent für Anwendungen verfügbar sein.

Die Scharnierposition und -grenzen müssen relativ zum Anwendungsfenster angegeben werden, das durch ein Context identifiziert wird, das an die API übergeben wird. Wenn sich die Grenzen des Anwendungsfensters nicht mit den Grenzen des Scharniers überschneiden, darf das Scharnier DisplayFeature nicht gemeldet werden. Es ist auch zulässig, die Displayfunktionen nicht zu melden, wenn ihre Position möglicherweise nicht zuverlässig gemeldet wird, z. B. wenn ein Anwendungsfenster im Mehrfenstermodus oder im Kompatibilitäts-Letterboxing-Modus vom Nutzer frei verschoben werden kann.

Bei Faltfunktionen müssen Statusaktualisierungen gemeldet werden, wenn sich die Scharnierposition zwischen den stabilen Zuständen ändert. Im Standardzustand (flache Darstellung) muss die API FoldingFeature.State.FLAT zurückgeben. Wenn die Gerätehardware in einem halb gefalteten Zustand stabil bleibt, muss die API FoldingFeature.State.HALF_OPENED melden. In der API gibt es keinen geschlossenen Status, da das Anwendungsfenster in diesem Fall entweder nicht sichtbar wäre oder die Scharniergrenzen nicht überschreiten würde.

Gerätekonfiguration

Zur Unterstützung der Implementierung der Faltfunktion müssen OEMs Folgendes tun:

• Konfigurieren Sie die Gerätestatus in device_state_configuration.xml, die von DeviceStateManagerService verwendet werden sollen. Weitere Informationen finden Sie unter DeviceStateProviderImpl.java.

  Wenn die Standardimplementierungen von DeviceStateProvider oder DeviceStatePolicy nicht für das Gerät geeignet sind, kann eine benutzerdefinierte Implementierung verwendet werden.

• Aktivieren Sie das Erweiterungsmodul, wie im Abschnitt Verteilung des Erweiterungsmoduls beschrieben.

• Geben Sie den Speicherort der Displayfunktionen in der String-Ressource com.android.internal.R.string.config_display_features an (normalerweise in frameworks/base/core/res/res/values/config.xml im Geräte-Overlay).

  Das erwartete Format für den String ist:

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

  type kann entweder fold oder hinge sein. Die Werte für left, top, right und bottom sind ganzzahlige Pixelkoordinaten im Koordinatensystem des Displays in der natürlichen Ausrichtung des Displays. Der Konfigurationsstring kann mehrere durch Semikolons getrennte Displayfunktionen enthalten.

  Beispiel:

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

• Definiere die Zuordnung zwischen den internen Gerätestatus-IDs, die in DeviceStateManager verwendet werden, und den öffentlichen Statuskonstanten, die an Entwickler in com.android.internal.R.array.config_device_state_postures gesendet werden.

  Das erwartete Format für jeden Eintrag ist:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  Folgende Statuskennzeichnungen werden unterstützt:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: Für den Bundesstaat sind keine Funktionen zum Falten verfügbar. Das kann beispielsweise der geschlossene Zustand eines typischen faltbaren Geräts sein, bei dem sich das Hauptdisplay auf der Innenseite befindet.
  • COMMON_STATE_HALF_OPENED = 2: Das faltbare Smartphone ist halb aufgeklappt.
  • COMMON_STATE_FLAT = 3: Das faltbare Display ist flach. Das kann beispielsweise der geöffnete Zustand des typischen faltbaren Geräts mit dem Hauptdisplay auf der Innenseite sein.
  • COMMON_STATE_USE_BASE_STATE = 1000: In Android 14 ein Wert, der für emulierte Status verwendet werden kann, in denen der Scharnierstatus aus dem Basisstatus abgeleitet wird, wie in CommonFoldingFeature.java definiert.

  Weitere Informationen finden Sie unter DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int).

  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>
  

Fensterfläche

Die Fensterbereichskomponente bietet eine Reihe von Funktionen, mit denen Anwendungen auf einigen faltbaren Geräten und Geräten mit mehreren Displays auf zusätzliche Displays und Displaybereiche zugreifen können.

Im Rückdisplaymodus kann eine Anwendung die Benutzeroberfläche für die Kameravorschau auf dem Außendisplay eines faltbaren Geräts anzeigen, damit die Hauptkamera des Geräts für Selfies und Videos verwendet werden kann. Geräte mit einem Android-kompatiblen (gemäß Android CDD in Bezug auf Attribute wie Größe, Dichte und verfügbare Navigationshilfen) Cover-Display, das mit den Rückkameras des Geräts übereinstimmt, müssen den Zugriff auf den Rückdisplaymodus ermöglichen.

Unter Android 14 können Apps, die auf dem inneren Display eines faltbaren Geräts ausgeführt werden, im Dual-Display-Modus zusätzliche Inhalte auf dem Cover-Display anzeigen, das anderen Nutzern zugewandt ist. Auf dem Cover-Display kann beispielsweise die Kameravorschau für die Person angezeigt werden, die fotografiert oder gefilmt wird.

Gerätekonfiguration

Zur Unterstützung der Implementierung der Faltfunktion müssen OEMs Folgendes tun:

• Konfigurieren Sie die Gerätestatus in device_state_configuration.xml, die von DeviceStateManagerService verwendet werden sollen. Weitere Informationen finden Sie unter DeviceStateProviderImpl.java.

  Wenn die Standardimplementierung von DeviceStateProvider oder DeviceStatePolicy 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 Geräte, die sich nach innen falten lassen und gefaltete Zustände unterstützen, müssen Sie die entsprechenden Status-IDs in com.android.internal.R.array.config_foldedDeviceStates auflisten.

• Für Geräte, die nach innen gefaltet werden und einen halb gefalteten Zustand unterstützen (das 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 Modus für das Rückdisplay unterstützen:

  • Liste die entsprechenden Status in com.android.internal.R.array.config_rearDisplayDeviceStates für DeviceStateManager auf.
  • Geben Sie die physische Displayadresse des Displays auf der Rückseite 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 ein, damit sie für Anwendungen verfügbar ist.

• Auf Geräten mit Android 14, die den Dual-Display-Modus (gleichzeitige Anzeige) unterstützen:

  • Setzen Sie com.android.internal.R.bool.config_supportsConcurrentInternalDisplays auf true.
  • Geben Sie die physische Displayadresse des Displays auf der Rückseite in com.android.internal.R.config_deviceStateConcurrentRearDisplay an.
  • Geben Sie die Statuskennung in com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay an, die von Erweiterungen verwendet werden soll, wenn die Kennung für Anwendungen verfügbar gemacht werden soll.
  • Fügen Sie die Statuskennung in com.android.internal.R.array.config_deviceStatesAvailableForAppRequests ein, damit sie für Anwendungen verfügbar ist.

Bestätigung

OEMs müssen ihre Implementierungen überprüfen, um das erwartete Verhalten in gängigen Szenarien sicherzustellen. CTS-Tests und Tests mit Jetpack WindowManager sind für OEMs verfügbar, um Implementierungen zu testen.

CTS-Tests

Informationen zum Ausführen der CTS-Tests finden Sie unter CTS-Tests ausführen. Die CTS-Tests für Jetpack WindowManager befinden sich unter cts/tests/framework/base/windowmanager/jetpack/. Der Name des Testmoduls ist CtsWindowManagerJetpackTestCases.

WindowManager-Tests

Wenn Sie die Jetpack WindowManager-Tests herunterladen möchten, folgen Sie der Android Jetpack-Anleitung. Die Tests befinden sich in der Fensterbibliothek im Modul window:window: window/window/src/androidTest/.

So führen Sie die Gerätetests für das Modul window:window über die Befehlszeile aus:

1. Schließen Sie ein Gerät an, auf dem die Entwickleroptionen und das USB-Debugging aktiviert sind.
2. Dem Computer erlauben, das Gerät zu debuggen
3. Öffnen Sie eine Shell im Stammverzeichnis des androidx-Repositorys.
4. Wechseln Sie in das Verzeichnis framework/support.
5. Führen Sie dazu diesen Befehl aus: ./gradlew window:window:connectedAndroidTest.
6. Analysieren Sie die Ergebnisse.

So führen Sie die Tests in Android Studio aus:

1. Öffnen Sie Android Studio.
2. Schließen Sie ein Gerät an, auf dem die Entwickleroptionen und das USB-Debugging aktiviert sind.
3. Dem Computer erlauben, das Gerät zu debuggen
4. Rufen Sie einen Test in der Fensterbibliothek des Fenstermoduls auf.
5. Öffnen Sie eine Testklasse und führen Sie sie mit den grünen Pfeilen 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 Sie sich die Ausgabe der Shell ansehen. Einige Tests werden übersprungen, wenn das Gerät bestimmte Voraussetzungen nicht erfüllt. Die Ergebnisse werden an einem Standardspeicherort gespeichert und Analysten können ein Script schreiben, um die Analyse der Ergebnisse zu automatisieren.