WindowManager-Erweiterungen

Jetpack WindowManager können App-Entwickler neue Geräteformfaktoren und Umgebungen mit mehreren Fenstern.

WindowManager Extensions (Extensions) ist ein Opt-in-Android-Plattformmodul, aktiviert eine Vielzahl von Jetpack WindowManager-Funktionen. Das Modul ist implementiert, bei AOSP in frameworks/base/libs/WindowManager/Jetpack und auf Geräten ausgeliefert werden, die die WindowManager-Funktionen unterstützen.

Verteilung des Erweiterungsmoduls

Erweiterungen werden in einer .jar-Bibliothek kompiliert und im system_ext platziert auf einem Gerät, wenn Erweiterungen im Geräte-Makefile aktiviert sind.

Um Erweiterungen auf einem Gerät zu aktivieren, fügen Sie dem Produktgerät Folgendes hinzu: Makefile:

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

Dadurch werden androidx.window.extensions und androidx.window.sidecar aktiviert. Paket auf dem Gerät und legt die Eigenschaft persist.wm.extensions.enabled fest. Durch die Aufnahme dieser Pakete in das Makefile werden auch Deklarationen in etc/permissions/ und stellt sie für Anwendungsprozesse zur Verfügung. Normalerweise werden im Rahmen des Anwendungsprozesses unter -Laufzeit bei Verwendung der WindowManager-Bibliothek von Jetpack, wodurch ihre Vorgang ähnlich dem clientseitigen Framework-Code, wie im Folgenden Abbildung:

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">
</ph> Abbildung 1: In die Anwendung geladene WindowManager-Erweiterungen ähnlich wie Plattformcode.

Das Modul androidx.window.extensions ist das aktuelle Modul für Erweiterungen unter eine aktive Entwicklung. Das Modul androidx.window.sidecar ist ein Legacy-Modul aus Gründen der Kompatibilität mit den frühesten Versionen von Jetpack WindowManager, aber die Sidecar-Datei wird nicht mehr aktiv verwaltet.

Die folgende Abbildung zeigt die Logik zur Bestimmung der Verwendung von androidx.window.extensions oder androidx.window.sidecar.

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">
</ph> Abbildung 2: Entscheidungsbaum für den Zugriff 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 Bildschirmen unterstützen. Zu den Funktionsbereichen gehören:

OEM-Implementierungen von Erweiterungen können Null-Komponenten oder -Komponenten mit Standard- oder Stub-Implementierungen der Methoden in der WindowExtensions wenn die Hardware des Geräts die entsprechenden Funktionen nicht unterstützt, es sei denn, die Funktion wird ausdrücklich in Kompatibilitätsdefinitionsdokument (CDD) 7.1.1.1.

Erweiterungen und Jetpack APIs

Das WindowManager Extensions-Modul bietet neben der die APIs der öffentlichen Plattform. Das Erweiterungsmodul wird in einem nicht für Entwickler, androidx.window.extensions Jetpack-Bibliothek, sodass Jetpack WindowManager (androidx.window) bei der Kompilierung darauf verweisen kann. Oberfläche der Extensions API in der Regel stellt untergeordnete APIs bereit.

Die von Erweiterungen bereitgestellten APIs sind für die Nutzung durch Jetpack bestimmt. Nur WindowManager-Bibliothek. Die Extensions APIs sollen nicht von direkt von Anwendungsentwicklern. Die Erweiterungsbibliothek darf nicht als Abhängigkeit für eine Anwendung in der Gradle-Build-Datei, um sicherzustellen, Funktionalität. Vorkompilierung der Erweiterungsbibliothek in einer Anwendung vermeiden directly; sollten Sie sich stattdessen auf das Laden der Laufzeit verlassen, um zu verhindern, von vorkompilierten und durch Laufzeit bereitgestellten Erweiterungsklassen.

Jetpack WindowManager (androidx.window) soll als Anwendung hinzugefügt werden und stellt die öffentlichen Entwickler-APIs bereit, einschließlich derer für WindowManager Extensions-Funktionen. Die WindowManager-Bibliothek wird automatisch lädt Erweiterungen in den Anwendungsprozess und schließt die Erweiterungs-APIs in übergeordnete Abstraktionen und fokussierter Schnittstellen. Die WindowManager Jetpack APIs entsprechen den Standards moderner die Entwicklung von Android-Apps Interoperabilität durch eine gute Integration in Codebasen, die andere AndroidX- Bibliotheken.

Versionen und Updates von Erweiterungen

Das Modul „Erweiterungen“ kann zusammen mit der Android-Plattform jährlich aktualisiert werden oder vierteljährliche Updates. Durch vierteljährliche Aktualisierungen kann das Extensions API-Level zwischen den API-Updates der Android-Plattform erhöht, was eine schnellere Iteration und So erhalten OEMs die Möglichkeit, offiziellen API-Zugriff auf neue Funktionen hinzuzufügen. kurz vor der Markteinführung von Hardware.

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

Android-Plattformversion WindowManager Extensions API-Ebene API-Version androidx.window.extensions
Android 15 6 1.5.0 (demnächst verfügbar)
Android 14 QPR3 5 1.4.0 (demnächst verfügbar)
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

Die Extensions API-Ebene (mittlere Spalte) wird jedes Mal erhöht, wenn ein Ergänzung zur vorhandenen stabilen API-Oberfläche (rechte Spalte).

<ph type="x-smartling-placeholder">

Abwärts- und Vorwärtskompatibilität

Jetpack WindowManager kümmert sich um den komplexen Umgang mit häufigen API-Levels Updates, schnelle API-Entwicklung und Abwärtskompatibilität. Wenn der Bibliothekscode ausgeführt wird, prüft die Bibliothek die deklarierten Extensions API-Level und bietet Zugriff auf Funktionen gemäß den deklarierten

Um eine Anwendung vor einem Absturz während der Laufzeit zu schützen, führt WindowManager eine Java-Laufzeit-Reflexionsprüfung der verfügbaren Extensions APIs gemäß das deklarierte Extensions API-Level. Bei einer Diskrepanz kann WindowManager die Nutzung von Erweiterungen (teilweise oder vollständig) deaktivieren und die für die Anwendung nicht zur Verfügung stehen.

WindowManager-Erweiterungen sind als system_ext-Modul implementiert, das privaten Plattform-APIs für den Aufruf von WindowManager Core, DeviceStateManager, und andere Systemdienste bei der Implementierung der Erweiterungsfunktionen.

Die Kompatibilität mit Vorabveröffentlichungen von Erweiterungen kann nicht aufrechterhalten werden vor dem entsprechenden vierteljährlichen oder jährlichen Release der Android-Plattform mit und die Versionen werden finalisiert. Der vollständige Verlauf der Extensions APIs kann aus dem Release-Zweig window:extensions:extensions API-Textdateien.

Neuere Versionen von Erweiterungen müssen weiterhin mit älteren Versionen von funktionieren. WindowManager, der zur Aufrechterhaltung der Aufwärtskompatibilität in Anwendungen kompiliert wurde. Bis dass in jeder neuen Version der Extensions API nur neue APIs und werden ältere nicht entfernt. Daher werden Anwendungen mit älterer WindowManager-Version Versionen können die älteren Extensions APIs weiterhin verwenden, in denen die Apps kompiliert wurden. zu vergleichen.

Durch die CTS-Überprüfung wird sichergestellt, dass für jede deklarierte Version der Extensions APIs auf der sind alle APIs dafür und für Vorgängerversionen vorhanden und funktionsfähig.

Leistung

Das Erweiterungsmodul wird ab Android 14 (API-Level 34) standardmäßig in Nicht-Bootclasspath-Ladeprogrammen im Cache gespeichert. Die Leistung wird also nicht beeinträchtigt, weil das Modul beim Start der App in den Arbeitsspeicher geladen wird. Die Verwendung einzelner Modulfunktionen kann einen geringen Einfluss auf die Leistungsmerkmale von Anwendungen haben, wenn zusätzliche IPC-Aufrufe zwischen dem Client und dem Server ausgeführt werden.

Module

Eingebettete Aktivitäten

Die Aktivitätseinbettung Komponente bietet eine Reihe von Funktionen, mit denen Anwendungen ihre Darstellung des Aktivitätsfensters innerhalb der Grenzen der übergeordneten Anwendung. Dieses umfasst die gleichzeitige Anzeige von zwei Aktivitäten in einer Mehrfensterlayout, das die Optimierung großer Bildschirme für Legacy- Anwendungen.

Die Komponente zum Einbetten von Aktivitäten muss auf allen Geräten verfügbar sein, integriertes Display, das größer oder gleich sw600 dp ist. Auf Geräten, die externe Bildschirme unterstützen, muss auch die Einbettung von Aktivitäten aktiviert sein Verbindungen, da die Anwendung bei externen Verbindungen Bildschirme sind zur Laufzeit verbunden.

Gerätekonfiguration

Abgesehen von der Aktivierung der Erweiterungen ist keine spezielle Gerätekonfiguration erforderlich. wie unter Erweiterungsmodulverteilung beschrieben. . Erweiterungen sollten daher auf allen Geräten aktiviert werden, Mehrfenstermodus. Künftige Android-Versionen werden wahrscheinlich bei gängigen Konfigurationen von Handheld-Geräten und Geräten mit großen Bildschirmen erforderlich.

Informationen zum Fensterlayout

Die Komponente „Fenster-Layout-Informationen“ gibt die Position und den Zustand des Scharnier an einem faltbaren Gerät, wenn das Scharnier durch ein Anwendungsfenster kreuzt. Mithilfe von Informationen zum Fensterlayout können Anwendungen auf optimierte Layouts im Modus „Auf dem Tisch“ auf faltbaren Geräten. Weitere Informationen finden Sie unter App mit Scrollen sichtbar machen .

Faltbare Android-Geräte mit einem Scharnier, das getrennte oder Die Bereiche des kontinuierlichen Anzeigefelds müssen die Informationen zum Scharnier verfügbar für Apps über WindowLayoutComponent.

Die Position und die Grenzen des Scharniers müssen relativ zur Anwendung angegeben werden Fenster, das durch eine an die API übergebene Context identifiziert wird. Wenn das Bewerbungsfenster nicht mit den Scharniergrenzen schneiden, DisplayFeature dürfen 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 eine Anwendung Fenster kann vom Nutzer im Mehrfenstermodus frei verschoben werden. Kompatibilitäts-Letterbox-Modus.

Für Faltfunktionen: Statusaktualisierungen müssen gemeldet werden, wenn sich die Position des Scharniers zwischen dem stabilen Status haben. In einem flachen Anzeigezustand muss die API standardmäßig FoldingFeature.State.FLAT Wenn die Hardware des Geräts in einem halb zusammengefalteten Modus in einem stabilen Zustand belassen werden kann, Die API muss FoldingFeature.State.HALF_OPENED melden. In der API gibt es keinen geschlossenen Status, da in diesem Fall das Anwendungsfenster entweder nicht sichtbar sind oder die Scharniergrenzen nicht überschreiten.

Gerätekonfiguration

Um die Implementierung der Faltfunktion zu unterstützen, müssen OEMs Folgendes tun:

  • Konfigurieren Sie die Gerätestatus in device_state_configuration.xml, die von DeviceStateManagerService. Weitere Informationen finden Sie unter 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 in den Abschnitt Verteilung der Module für Erweiterungen.

  • Geben Sie den Speicherort der Anzeigeelemente in der com.android.internal.R.string.config_display_features an String-Ressource (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. Werte für left, top, right und bottom sind ganzzahlige Pixelkoordinaten im Darstellungskoordinatenraum in der natürlichen Displayausrichtung. Der Konfigurationsstring kann mehrere Anzeigeelemente, getrennt durch Semikolons.

    Beispiel:

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

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

    Das erwartete Format für jeden Eintrag ist:

    <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

    Folgende Status-IDs werden unterstützt:

    • COMMON_STATE_NO_FOLDING_FEATURES = 1: Der Zustand hat keine faltbaren Elemente. Bericht. Es kann sich beispielsweise um den geschlossenen Zustand der üblichen Auf- und Zuklappung handeln. Gerät mit dem Hauptbildschirm an der inneren Seite.
    • COMMON_STATE_HALF_OPENED = 2: Die Faltfunktion ist zur Hälfte geöffnet.
    • COMMON_STATE_FLAT = 3: Die Faltfunktion ist flach. Es kann sich zum Beispiel um den geöffneten Zustand eines typischen auf- und zuklappbaren Geräts handeln, bei dem sich der Hauptbildschirm an der Innenseite befindet.
    • COMMON_STATE_USE_BASE_STATE = 1000: in Android 14, ein Wert, der für emulierte Zustand, bei dem der Scharnierstatus anhand des Basiszustands abgeleitet wird, wie in den CommonFoldingFeature.java

    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>

Fensterbereich

Die Fensterbereich-Komponente bietet eine Reihe von Funktionen, mit denen Sie Zugriff auf zusätzliche Displays und Bereiche auf einigen faltbaren und Geräte mit mehreren Displays.

Mit dem Rückdisplaymodus kann eine App die Benutzeroberfläche der Kameravorschau auf der Display eines faltbaren Geräts abdecken, um die Kamera des Hauptgeräts für Selfies und Videos. Geräte mit einem Android-kompatiblen (gemäß den Android-CDD in Bezug auf Attribute wie Größe, Dichte und (verfügbaren Navigationsoptionen) ein Deckblatt, das auf der Rückseite des Geräts ausgerichtet ist. Kameras müssen Zugriff auf den Rückdisplaymodus haben.

Unter Android 14 können Apps, die auf dem inneren Display eines faltbaren Geräts ausgeführt werden, mit dem Modus für zwei Displays zusätzliche Inhalte auf dem Coverdisplay für andere Nutzer einblenden. Beispielsweise kann der Person, die fotografiert oder aufgenommen wird, auf dem Deckblatt die Vorschau der Kamera angezeigt werden.

Gerätekonfiguration

Um die Implementierung der Faltfunktion zu unterstützen, müssen OEMs Folgendes tun:

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

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

  • Geben Sie für faltbare Geräte, die den offenen oder flachen Modus unterstützen, das entsprechende Status-IDs in com.android.internal.R.array.config_openDeviceStates.

  • Geben Sie für Geräte, die aufgeklappt werden können, die zugeklappt werden können, Status-IDs in com.android.internal.R.array.config_foldedDeviceStates.

  • Für zusammengeklappte Geräte, die zur Hälfte zusammengeklappt sind (Scharnier ist zur Hälfte geöffnet) wie z. B. ein Laptop), listen Sie die entsprechenden Status in com.android.internal.R.array.config_halfFoldedDeviceStates

  • Bei Geräten, die den Rückdisplaymodus unterstützen:

    • Listen Sie die entsprechenden Status in com.android.internal.R.array.config_rearDisplayDeviceStates für DeviceStateManager auf.
    • Gib die Adresse des hinteren Displays in com.android.internal.R.string.config_rearDisplayPhysicalAddress an.
    • Geben Sie in com.android.internal.R.integer.config_deviceStateRearDisplay die ID des Bundesstaats an, die von Erweiterungen verwendet werden soll.
    • Fügen Sie die Status-ID in com.android.internal.R.array.config_deviceStatesAvailableForAppRequests hinzu, um sie Anwendungen zur Verfügung zu stellen.

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

    • Setzen Sie com.android.internal.R.bool.config_supportsConcurrentInternalDisplays auf true.
    • Gib die Adresse des hinteren Displays in com.android.internal.R.config_deviceStateConcurrentRearDisplay an.
    • Geben Sie die Bundesstaatkennung 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 Status-ID in com.android.internal.R.array.config_deviceStatesAvailableForAppRequests hinzu, um sie Anwendungen zur Verfügung zu stellen.

Bestätigung

OEMs müssen ihre Implementierungen überprüfen, um sicherzustellen, dass das erwartete Verhalten gemeinsam ist. Szenarien durchführen. CTS-Tests und Tests mit Jetpack WindowManager sind für OEMs verfügbar. zum Testen von Implementierungen.

CTS-Tests

Informationen zum Ausführen der CTS-Tests finden Sie unter CTS-Tests ausführen. CTS Tests im Zusammenhang mit Jetpack WindowManager liegen unter cts/tests/framework/base/windowmanager/jetpack/. Der Name des Testmoduls lautet CtsWindowManagerJetpackTestCases.

WindowManager-Tests

Um die Jetpack WindowManager-Tests herunterzuladen, Anleitung für Android Jetpack Die Tests befinden sich in der Fensterbibliothek unter dem window:window-Modul: window/window/src/androidTest/.

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

  1. Schließen Sie ein Gerät an, bei 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. Ändern Sie das Verzeichnis in framework/support.
  5. Führen Sie den folgenden Befehl aus: ./gradlew window:window:connectedAndroidTest.
  6. Analysieren Sie die Ergebnisse.

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

  1. Öffnen Sie Android Studio.
  2. Schließen Sie ein Gerät an, bei dem Entwickleroptionen und USB-Debugging aktiviert sind.
  3. Erlauben Sie dem Computer, 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 der Editor.

Alternativ kannst du eine Konfiguration in Android Studio erstellen, um einen Test auszuführen eine Testklasse oder alle Tests in einem Modul.

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 sind an einem Standardspeicherort gespeichert, und Fachkräfte für Datenanalyse können ein Skript schreiben, um die Analyse der Ergebnisse.