Biblioteka Jetpack WindowManager umożliwia twórcom aplikacji obsługę nowych urządzeń i środowisk z wieloma oknami.
Rozszerzenia WindowManager (Rozszerzenia) to opcjonalny moduł platformy Android, który umożliwia korzystanie z różnych funkcji Jetpack WindowManager. Moduł jest zaimplementowany w AOSP w frameworks/base/libs/WindowManager/Jetpack i dostarczany na urządzeniach obsługujących funkcje WindowManager.
Dystrybucja modułów rozszerzeń
Rozszerzenia są kompilowane do biblioteki .jar i umieszczane na partycji system_ext na urządzeniu, jeśli w pliku makefile urządzenia włączono rozszerzenia.
Aby włączyć rozszerzenia na urządzeniu, dodaj następujące elementy do pliku makefile urządzenia produktu:
$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)
Spowoduje to włączenie pakietów androidx.window.extensions i androidx.window.sidecar na urządzeniu i ustawienie właściwości persist.wm.extensions.enabled . Dołączenie tych pakietów do pliku makefile powoduje również umieszczenie deklaracji w etc/permissions/ , udostępniając je procesom aplikacji. Zwykle moduły są ładowane i wykonywane jako część procesu aplikacji w czasie wykonywania, gdy są używane przez bibliotekę Jetpack WindowManager, co sprawia, że jej działanie jest podobne do kodu frameworka po stronie klienta, jak pokazano na poniższym rysunku:
Moduł androidx.window.extensions jest aktualnie rozwijanym modułem rozszerzeń. Moduł androidx.window.sidecar to starszy moduł dołączony w celu zapewnienia zgodności z najwcześniejszymi wersjami Jetpack WindowManager, ale wózek boczny nie jest już aktywnie obsługiwany.
Poniższy rysunek przedstawia logikę określania użycia androidx.window.extensions lub androidx.window.sidecar .
androidx.window.extensions lub androidx.window.sidecar .Moduły rozszerzeń
Rozszerzenia zapewniają funkcje okienkowe dla składanych urządzeń z dużym ekranem i urządzeń obsługujących wyświetlanie okien na wyświetlaczach zewnętrznych. Obszary funkcji obejmują:
Implementacje OEM rozszerzeń mogą zapewniać komponenty zerowe lub komponenty z domyślnymi lub zastępczymi implementacjami metod w interfejsie WindowExtensions , jeśli sprzęt urządzenia nie obsługuje odpowiednich funkcji, chyba że funkcja ta jest wyraźnie wymagana w dokumencie definicji zgodności (CDD) 7.1.1.1 .
Rozszerzenia i interfejsy API Jetpack
Moduł rozszerzeń WindowManager udostępnia własną powierzchnię API jako uzupełnienie interfejsów API platformy publicznej. Moduł rozszerzeń jest rozwijany publicznie w niedostępnej dla programistów bibliotece Jetpack androidx.window.extensions , dzięki czemu Jetpack WindowManager ( androidx.window ) może łączyć się z nim w czasie kompilacji. Powierzchnia API rozszerzeń zazwyczaj udostępnia interfejsy API niższego poziomu.
Interfejsy API udostępniane przez rozszerzenia są przeznaczone wyłącznie do użytku przez bibliotekę Jetpack WindowManager. Interfejsy API rozszerzeń nie są przeznaczone do bezpośredniego wywoływania przez twórców aplikacji. Biblioteki rozszerzeń nie można dodawać jako zależności dla aplikacji w pliku kompilacji Gradle, aby zapewnić poprawną funkcjonalność. Unikaj wstępnej kompilacji biblioteki rozszerzeń bezpośrednio do aplikacji; zamiast tego polegaj na ładowaniu w czasie wykonywania, aby zapobiec przypadkowi ładowania kombinacji klas rozszerzeń wstępnie skompilowanych i dostarczonych w czasie wykonywania.
Jetpack WindowManager ( androidx.window ) ma zostać dodany jako zależność aplikacji i zapewnia publiczne interfejsy API przeznaczone dla programistów, w tym te dla funkcji rozszerzeń WindowManager. Biblioteka WindowManager automatycznie ładuje rozszerzenia do procesu aplikacji i otacza interfejsy API rozszerzeń niższego poziomu w abstrakcje wyższego poziomu i bardziej skoncentrowane interfejsy. Interfejsy API WindowManager Jetpack są zgodne ze standardami tworzenia nowoczesnych aplikacji dla systemu Android i mają zapewniać wygodną interoperacyjność poprzez dobrą integrację z bazami kodu korzystającymi z innych bibliotek AndroidX.
Wersje rozszerzeń i aktualizacje
Moduł Rozszerzeń można aktualizować wraz z rocznymi lub kwartalnymi aktualizacjami platformy Android. Kwartalne aktualizacje umożliwiają podniesienie poziomu interfejsu API rozszerzeń pomiędzy aktualizacjami interfejsu API platformy Android, umożliwiając szybszą iterację i zapewniając producentom OEM możliwość dodania oficjalnego dostępu API do nowych funkcji w pobliżu premier sprzętu.
W poniższej tabeli wymieniono wersje interfejsu API androidx.window.extensions dla różnych wydań systemu Android.
| Wersja na platformę Android | Poziom API rozszerzeń WindowManager | Wersja API androidx.window.extensions |
|---|---|---|
| Androida 14 | 3 | 1.2.0 |
| Androida 13 QPR3 | 2 | 1.1.0 |
| Androida 13 | 1 | 1.0.0 |
| Androida 12L | 1 | 1.0.0 |
Poziom API rozszerzeń (kolumna środkowa) jest zwiększany za każdym razem, gdy do istniejącej stabilnej powierzchni API zostanie dodany (prawa kolumna).
Kompatybilność wsteczna i do przodu
Jetpack WindowManager radzi sobie ze złożonością związaną z częstymi aktualizacjami poziomu API, szybką ewolucją API i kompatybilnością wsteczną. Gdy w procesie aplikacji wykonywany jest kod biblioteki, biblioteka sprawdza zadeklarowany poziom API rozszerzeń i zapewnia dostęp do funkcjonalności zgodnie z zadeklarowanym poziomem.
Aby zabezpieczyć aplikację przed awarią w czasie wykonywania, WindowManager przeprowadza także w czasie wykonywania kontrolę odbicia Java w zakresie dostępnych API rozszerzeń zgodnie z zadeklarowanym poziomem API rozszerzeń. W przypadku niezgodności WindowManager może wyłączyć korzystanie z rozszerzeń (częściowo lub całkowicie) i zgłosić odpowiednie funkcje jako niedostępne dla aplikacji.
Rozszerzenia WindowManager są implementowane jako moduł system_ext , który wykorzystuje interfejsy API platformy prywatnej do wywoływania rdzenia WindowManager, DeviceStateManager i innych usług systemowych w ramach implementacji funkcji rozszerzeń.
Zgodność z przedpremierowymi wersjami rozszerzeń może nie zostać zachowana przed odpowiednią kwartalną lub roczną wersją platformy Android, na której wersje są finalizowane. Pełną historię interfejsów API rozszerzeń można znaleźć w gałęzi wydania window:extensions:extensions API files .
Nowsze wersje rozszerzeń muszą w dalszym ciągu współpracować ze starszymi wersjami WindowManager wkompilowanymi w aplikacje, aby zachować kompatybilność z przyszłymi wersjami. Aby to zapewnić, każda nowa wersja interfejsu API rozszerzeń dodaje tylko nowe interfejsy API i nie usuwa starszych. W rezultacie aplikacje ze starszymi wersjami programu WindowManager mogą w dalszym ciągu korzystać ze starszych interfejsów API rozszerzeń, dla których aplikacje zostały skompilowane.
Weryfikacja CTS gwarantuje, że w przypadku dowolnej zadeklarowanej wersji interfejsów API rozszerzeń na urządzeniu wszystkie interfejsy API tej i poprzednich wersji są obecne i funkcjonalne.
Wydajność
Moduł rozszerzeń jest domyślnie buforowany w modułach ładujących klasy systemowe inne niż bootclasspath, począwszy od Androida 14 (poziom API 34), więc ładowanie modułu do pamięci podczas uruchamiania aplikacji nie ma wpływu na wydajność. Korzystanie z poszczególnych funkcji modułu może mieć niewielki wpływ na charakterystykę wydajności aplikacji, gdy między klientem a serwerem wykonywane są dodatkowe połączenia IPC.
Moduły
Osadzanie aktywności
Komponent osadzania działań udostępnia zestaw funkcji umożliwiających aplikacjom organizowanie prezentacji okien działań w granicach aplikacji nadrzędnej. Obejmuje to jednoczesne wyświetlanie dwóch działań obok siebie w układzie wielopanelowym, co ułatwia optymalizację dużego ekranu w przypadku starszych aplikacji.
Komponent osadzający aktywność musi być dostępny na wszystkich urządzeniach, które mają wbudowany wyświetlacz o rozmiarze równym lub większym niż sw600 dp . Osadzanie aktywności musi być także włączone na urządzeniach obsługujących połączenia z zewnętrznymi wyświetlaczami, ponieważ aplikacja może być wyświetlana w większym rozmiarze, gdy w czasie wykonywania podłączone są zewnętrzne wyświetlacze.
Konfiguracja urzadzenia
Nie jest wymagana żadna szczególna konfiguracja urządzenia poza włączeniem modułu rozszerzeń zgodnie z opisem w sekcji Dystrybucja modułów rozszerzeń . Sensowne jest włączenie rozszerzeń na wszystkich urządzeniach obsługujących tryb wielu okien. W przyszłych wersjach Androida prawdopodobnie będą wymagane rozszerzenia w typowych konfiguracjach urządzeń przenośnych i urządzeń z dużym ekranem.
Informacje o układzie okna
Komponent informacji o układzie okna identyfikuje położenie i stan zawiasu na urządzeniu składanym, gdy zawias przechodzi przez okno aplikacji. Informacje o układzie okna umożliwiają aplikacjom reagowanie i wyświetlanie zoptymalizowanych układów w trybie stołu na urządzeniach składanych. Aby uzyskać szczegółowe informacje na temat użycia, zobacz Spraw, aby Twoja aplikacja była świadoma składania .
Składane urządzenia z systemem Android zawierające zawias łączący oddzielne lub ciągłe obszary panelu wyświetlacza muszą udostępniać aplikacjom informacje o zawiasie za pośrednictwem WindowLayoutComponent .
Pozycję zawiasu i granice należy zgłosić w odniesieniu do okna aplikacji zidentyfikowanego przez Context przekazany do interfejsu API. Jeśli granice okna aplikacji nie przecinają się z granicami zawiasów, nie należy raportować funkcji DisplayFeature zawiasu. Dopuszczalne jest również niezgłaszanie funkcji wyświetlania, gdy ich położenie może nie zostać podane w sposób wiarygodny, na przykład gdy użytkownik może swobodnie przesuwać okno aplikacji w trybie wielu okien lub w trybie letterboxingu zgodności.
W przypadku funkcji składania aktualizacje stanu muszą być raportowane, gdy pozycja zawiasu zmienia się między stanami stabilnymi. Domyślnie w płaskim stanie wyświetlania interfejs API musi zgłaszać FoldingFeature.State.FLAT . Jeśli sprzęt urządzenia można pozostawić w trybie złożonym w stanie stabilnym, interfejs API musi zgłosić FoldingFeature.State.HALF_OPENED . W API nie ma stanu zamkniętego, gdyż w takim przypadku okno aplikacji albo nie byłoby widoczne, albo nie przekraczałoby granic zawiasów.
Konfiguracja urzadzenia
Aby wesprzeć implementację funkcji składania, producenci OEM muszą wykonać następujące czynności:
Skonfiguruj stany urządzeń w
device_state_configuration.xml, które mają być używane przezDeviceStateManagerService. Informacje można znaleźć w plikuDeviceStateProviderImpl.java.Jeśli domyślne implementacje
DeviceStateProviderlubDeviceStatePolicynie są odpowiednie dla urządzenia, można użyć implementacji niestandardowej.Włącz moduł rozszerzeń zgodnie z opisem w sekcji Dystrybucja modułów rozszerzeń .
Określ lokalizację funkcji wyświetlania w zasobie ciągu
com.android.internal.R.string.config_display_features(zwykle wframeworks/base/core/res/res/values/config.xmlw nakładce urządzenia).Oczekiwany format ciągu to:
<type>-[<left>,<top>,<right>,<bottom>]typemoże byćfoldlubhinge. Wartości dlaleft,top,rightibottomsą całkowitymi współrzędnymi pikseli w przestrzeni współrzędnych wyświetlania w naturalnej orientacji wyświetlania. Ciąg konfiguracyjny może zawierać wiele funkcji wyświetlania oddzielonych średnikami.Na przykład:
<!-- Jetpack WindowManager display features --> <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>Zdefiniuj mapowanie pomiędzy wewnętrznymi identyfikatorami stanu urządzenia używanymi w
DeviceStateManageri publicznymi stałymi stanu wysyłanymi do programistów wcom.android.internal.R.array.config_device_state_postures.Oczekiwany format każdego wpisu to:
<device_specific_state_identifier>:<Jetpack WindowManager state identifier>Obsługiwane identyfikatory stanu to:
-
COMMON_STATE_NO_FOLDING_FEATURES = 1: Stan nie ma żadnych funkcji składania do raportowania. Może to być na przykład stan zamknięty typowego urządzenia składanego z ekranem głównym po wewnętrznej stronie. -
COMMON_STATE_HALF_OPENED = 2: Funkcja składania jest otwarta do połowy. -
COMMON_STATE_FLAT = 3: Funkcja składania jest płaska. Może to być na przykład stan otwarty typowego urządzenia składanego z ekranem głównym po wewnętrznej stronie. -
COMMON_STATE_USE_BASE_STATE = 1000: w systemie Android 14: wartość, której można użyć w przypadku emulowanych stanów, w których stan zawiasu jest wyprowadzany przy użyciu stanu podstawowego, zgodnie z definicją wCommonFoldingFeature.java
Aby uzyskać więcej informacji, zobacz
DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int).Na przykład:
<!-- 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>-
Powierzchnia okna
Komponent obszaru okna udostępnia zestaw funkcji zapewniających aplikacjom dostęp do dodatkowych wyświetlaczy i obszarów wyświetlania na niektórych urządzeniach składanych i z wieloma wyświetlaczami.
Tryb tylnego wyświetlacza umożliwia aplikacji wyświetlanie interfejsu podglądu aparatu na wyświetlaczu na obudowie urządzenia składanego, co pozwala na korzystanie z aparatu głównego urządzenia do robienia selfie i nagrywania filmów. Urządzenia wyposażone w wyświetlacz zgodny z systemem Android (zgodnie z definicją zawartą w CDD systemu Android pod względem atrybutów, takich jak rozmiar, gęstość i dostępne możliwości nawigacji) pokrywający wyświetlacz dopasowany do tylnych kamer urządzenia muszą zapewniać dostęp do trybu wyświetlacza tylnego.
W systemie Android 14 tryb podwójnego wyświetlania umożliwia aplikacjom działającym na wewnętrznym wyświetlaczu urządzenia składanego pokazywanie dodatkowej zawartości na wyświetlaczu zewnętrznym zwróconym w stronę innych użytkowników; na przykład wyświetlacz na obudowie może pokazywać podgląd aparatu osobie fotografowanej lub nagrywanej.
Konfiguracja urzadzenia
Aby wesprzeć implementację funkcji składania, producenci OEM muszą wykonać następujące czynności:
Skonfiguruj stany urządzeń w
device_state_configuration.xml, które mają być używane przezDeviceStateManagerService. Więcej informacji można znaleźć wDeviceStateProviderImpl.java.Jeśli domyślna implementacja
DeviceStateProviderlubDeviceStatePolicynie jest odpowiednia dla urządzenia, można zastosować niestandardową implementację.W przypadku urządzeń składanych obsługujących tryb otwarty lub płaski określ odpowiednie identyfikatory stanu w
com.android.internal.R.array.config_openDeviceStates.W przypadku urządzeń składanych obsługujących stany złożone podaj odpowiednie identyfikatory stanu w
com.android.internal.R.array.config_foldedDeviceStates.W przypadku urządzeń składanych, które obsługują stan złożony na pół (zawias jest w połowie otwarty jak laptop), wypisz odpowiednie stany w
com.android.internal.R.array.config_halfFoldedDeviceStates.W przypadku urządzeń obsługujących tryb wyświetlacza tylnego:
- Lista odpowiednich stanów w
com.android.internal.R.array.config_rearDisplayDeviceStatesdlaDeviceStateManager. - Określ fizyczny adres wyświetlacza tylnego w
com.android.internal.R.string.config_rearDisplayPhysicalAddress. - Określ identyfikator stanu w
com.android.internal.R.integer.config_deviceStateRearDisplay, który będzie używany przez rozszerzenia. - Dodaj identyfikator stanu w
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests, aby udostępnić go aplikacjom.
- Lista odpowiednich stanów w
W systemie Android 14 w przypadku urządzeń obsługujących tryb podwójnego (jednoczesnego) wyświetlania:
- Ustaw
com.android.internal.R.bool.config_supportsConcurrentInternalDisplaysnatrue. - Określ fizyczny adres wyświetlacza tylnego w
com.android.internal.R.config_deviceStateConcurrentRearDisplay. - Określ identyfikator stanu w
com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay, który będzie używany przez rozszerzenia, jeśli identyfikator ma być udostępniany aplikacjom. - Dodaj identyfikator stanu w
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests, aby udostępnić go aplikacjom.
- Ustaw
Weryfikacja
Producenci OEM muszą zweryfikować swoje wdrożenia, aby zapewnić oczekiwane zachowanie w typowych scenariuszach. Testy CTS i testy przy użyciu Jetpack WindowManager są dostępne dla producentów OEM w celu testowania wdrożeń.
Testy CTS
Aby uruchomić testy CTS, zobacz Uruchamianie testów CTS . Testy CTS związane z Jetpack WindowManager znajdują się w cts/tests/framework/base/windowmanager/jetpack/ . Nazwa modułu testowego to CtsWindowManagerJetpackTestCases .
Testy WindowManagera
Aby pobrać testy Jetpack WindowManager, postępuj zgodnie z instrukcjami Android Jetpack . Testy znajdują się w bibliotece okna pod modułem window:window : window/window/src/androidTest/ .
Aby uruchomić testy urządzenia dla modułu window:window z wiersza poleceń, wykonaj następujące czynności:
- Podłącz urządzenie, które ma opcje programistyczne i włączone debugowanie USB.
- Zezwól komputerowi na debugowanie urządzenia.
- Otwórz powłokę w katalogu głównym repozytorium Androidx.
- Zmień katalog na
framework/support. - Uruchom następującą komendę:
./gradlew window:window:connectedAndroidTest. - Przeanalizuj wyniki.
Aby uruchomić testy z Android Studio, wykonaj następujące czynności:
- Otwórz Studio Androida.
- Podłącz urządzenie, które ma opcje programistyczne i włączone debugowanie USB.
- Zezwól komputerowi na debugowanie urządzenia.
- Przejdź do testu w bibliotece okna modułu okna.
- Otwórz klasę testową i uruchom ją, korzystając z zielonych strzałek po prawej stronie edytora.
Alternatywnie możesz utworzyć konfigurację w Android Studio, aby uruchomić metodę testową, klasę testową lub wszystkie testy w module.
Wyniki można analizować ręcznie, patrząc na dane wyjściowe powłoki. Niektóre testy są pomijane, jeśli urządzenie nie spełnia określonych założeń. Wyniki zapisywane są w standardowej lokalizacji, a analitycy mogą napisać skrypt automatyzujący analizę wyników.