WindowManager-Erweiterungen

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:

Abbildung 1. WindowManager-Erweiterungen, die ähnlich wie Plattformcode in den Anwendungsprozess geladen werden.

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 .

Abbildung 2. Entscheidungsbaum für den Zugriff auf 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 von DeviceStateManagerService verwendet werden sollen. Siehe DeviceStateProviderImpl.java als Referenz.

    Wenn die Standardimplementierungen von DeviceStateProvider oder DeviceStatePolicy 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 in frameworks/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 entweder fold oder hinge sein. Die Werte für left , top , right und bottom 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 in com.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 in CommonFoldingFeature.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 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 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ür DeviceStateManager 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.

  • Unter Android 14 für Geräte, die den dualen (gleichzeitigen) Anzeigemodus unterstützen:

    • Setzen Sie com.android.internal.R.bool.config_supportsConcurrentInternalDisplays auf true .
    • 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.

Ü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:

  1. Schließen Sie ein Gerät an, auf dem Entwickleroptionen und USB-Debugging aktiviert sind.
  2. Erlauben Sie dem Computer, 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 den folgenden Befehl aus: ./gradlew window:window:connectedAndroidTest .
  6. Analysieren Sie die Ergebnisse.

Gehen Sie wie folgt vor, um die Tests in Android Studio auszuführen:

  1. Öffnen Sie Android Studio.
  2. Schließen Sie ein Gerät an, auf dem Entwickleroptionen und USB-Debugging aktiviert sind.
  3. Erlauben Sie dem Computer, das Gerät zu debuggen.
  4. Navigieren Sie zu einem Test in der Fensterbibliothek des Fenstermoduls.
  5. Ö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.