Jetpack WindowManager umożliwia programistom aplikacji obsługę nowych formatów urządzeń środowisk z wieloma oknami.
WindowManager Extensions (Extensions) to zatwierdzany moduł platformy Androida, który
umożliwia korzystanie z różnych funkcji Jetpack WindowManager. Moduł został zaimplementowany
w AOSP w: frameworks/base/libs/WindowManager/Jetpack
i dostępne na urządzeniach obsługujących funkcje WindowManager.
Rozkład modułów rozszerzeń
Rozszerzenia są kompilowane w bibliotekę .jar
i umieszczane w sekcji system_ext
partycji na urządzeniu, jeśli w pliku marki urządzenia są włączone rozszerzenia.
Aby włączyć rozszerzenia na urządzeniu, dodaj ten kod do urządzenia usługi Makerfile:
$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)
Spowoduje to włączenie androidx.window.extensions
i androidx.window.sidecar
pakietów na urządzeniu i ustawia właściwość persist.wm.extensions.enabled
.
Umieszczenie tych pakietów w pliku Makefile spowoduje też umieszczenie deklaracji w
etc/permissions/
, udostępniając je procesom aplikacji. Normalnie
są ładowane i uruchamiane w ramach procesu aplikacji na
gdy jest używana przez bibliotekę Jetpack WindowManager, co sprawia, że
operacji podobnej do kodu platformy po stronie klienta, jak pokazano na tym przykładzie:
ilustracja:
![](https://source.android.com/static/docs/core/display/images/wm_extensions_in_app_process.png?authuser=4&hl=pl)
Moduł androidx.window.extensions
to obecny moduł rozszerzeń w
aktywny proces programowania. Moduł androidx.window.sidecar
jest starszą wersją
zawarte na potrzeby zgodności z najstarszymi wersjami Jetpack WindowManager,
ale materiały pomocnicze nie są już aktywnie obsługiwane.
Na poniższym rysunku przedstawiono logikę określania użycia
androidx.window.extensions
lub androidx.window.sidecar
.
![](https://source.android.com/static/docs/core/display/images/wm_extensions_decision_tree.png?authuser=4&hl=pl)
androidx.window.extensions
lub androidx.window.sidecar
.
Moduły rozszerzeń
Rozszerzenia umożliwiają korzystanie z okna na składanych urządzeniach z dużym ekranem. urządzeń obsługujących wyświetlanie okien na ekranach zewnętrznych. Dostępne obszary:
Implementacje rozszerzeń OEM mogą dostarczać komponenty lub komponenty o wartości null,
lub zbędne implementacje metod w
WindowExtensions
interfejsu, jeśli sprzęt urządzenia nie obsługuje odpowiednich funkcji.
o ile nie jest to wyraźnie wymagane w
Dokument z definicją zgodności (CDD) 7.1.1.1.
Rozszerzenia i interfejsy Jetpack API
Moduł rozszerzeń WindowManager udostępnia własną platformę API
interfejsów API platformy publicznej. Moduł Rozszerzenia jest opracowywany publicznie w
nieprzeznaczona dla programistów androidx.window.extensions
z bibliotek Jetpack, aby umożliwić Jetpack WindowManager;
(androidx.window
)
ale nie mogą utworzyć linku do niego podczas kompilowania. Interfejs API rozszerzeń zwykle
udostępnia interfejsy API niższego poziomu.
Jetpack ma używać interfejsów API udostępnianych przez rozszerzenia. tylko z biblioteki WindowManager. Interfejsy API rozszerzeń nie powinny być wywoływane przez bezpośrednio z deweloperami aplikacji. Biblioteki rozszerzeń nie można dodawać jako zależność dla aplikacji w pliku kompilacji Gradle, aby zapewnić prawidłowe funkcji. Unikaj wstępnego kompilowania biblioteki rozszerzeń do aplikacji bezpośrednio; polegaj na wczytaniu środowiska wykonawczego, aby zapobiec załadowaniu zestawu wstępnie skompilowanych i udostępnianych w czasie działania klas rozszerzeń.
Jetpack WindowManager (androidx.window
) należy dodać jako aplikację
i udostępnia publiczne interfejsy API dla programistów, w tym
dla funkcji rozszerzeń WindowManager. Biblioteka WindowManager automatycznie
wczytuje rozszerzenia do procesu aplikacji i opakowuje niższy poziom
Interfejsy API rozszerzeń do abstrakcji wyższego poziomu i bardziej ukierunkowanych
i interfejsów. Interfejsy API WindowManager Jetpack są zgodne ze standardami
programowania aplikacji na Androida. Mają one na celu zapewnienie
współdziałania dzięki integracji z bazami kodu, które korzystają z innych
biblioteki.
Wersje i aktualizacje rozszerzeń
Moduł rozszerzeń można aktualizować wraz z platformą Androida co roku lub aktualizacje kwartalne. Kwartalne aktualizacje umożliwiają zwiększenie poziomu interfejsu API rozszerzeń między aktualizacjami interfejsu API platformy Androida, co umożliwia szybszą iterację oraz umożliwienie producentom OEM przyznania oficjalnego dostępu do nowych funkcji interfejsu API w przypadku premiery sprzętu.
W poniższej tabeli znajdziesz listę wersji interfejsu API usługi androidx.window.extensions
dla:
różne wersje Androida.
Wersja platformy Androida | Poziom interfejsu WindowManager Extensions API | Wersja interfejsu API androidx.window.extensions |
---|---|---|
Android 15 | 6 | 1.5.0 (już wkrótce) |
Android 14 QPR3 | 5 | 1.4.0 (już wkrótce) |
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 |
Poziom interfejsu API rozszerzeń (kolumna środkowa) zwiększa się za każdym razem, gdy występuje do istniejącej stabilnej powierzchni interfejsu API (prawa kolumna).
Zgodność wstecz i do przodu
Jetpack WindowManager pomaga rozwiązywać złożoność obsługi częstego poziomu interfejsu API aktualizacji, szybkiej ewolucji interfejsów API i zgodności wstecznej. Gdy kod biblioteki jest wykonywana w procesie aplikacji, biblioteka sprawdza zadeklarowane poziom interfejsu API rozszerzeń i zapewnia dostęp do funkcji zgodnie z zadeklarowanym na poziomie 300%.
Aby chronić aplikację przed awariami w czasie działania, WindowManager wykonuje również sprawdzenia odbicia w JavaScripcie dostępnych interfejsów API rozszerzeń pod kątem zadeklarowanym poziomie interfejsu Extensions API. W przypadku niezgodności WindowManager może wyłącz korzystanie z rozszerzeń (częściowo lub całkowicie) i zgłoś odpowiednie funkcji niedostępnych dla aplikacji.
Rozszerzenia WindowManager są zaimplementowane jako moduł system_ext
używający
do wywoływania interfejsów API platformy prywatnej WindowManager
DeviceStateManager
,
i innych usług systemowych.
Zgodność nie może być zachowana z przedpremierowymi wersjami rozszerzeń
przed wydaniem odpowiedniej kwartalnej lub rocznej wersji platformy Androida
które pozwala określić wersje końcowe. Pełną historię interfejsów API rozszerzeń można
znaleziono w gałęzi wersji
Pliki tekstowe interfejsu API (window:extensions:extensions
).
Nowsze wersje rozszerzeń muszą nadal działać ze starszymi wersjami Narzędzie WindowManager skompilowane w aplikacje w celu zachowania zgodności z funkcją przekierowywania. Do zapewnienie, że każda nowa wersja interfejsu Extensions API dodaje tylko nowe ale nie usuwa starszych. Z tego powodu aplikacje korzystające ze starszej wersji WindowManagera mogą nadal korzystać ze starszych interfejsów API rozszerzeń skompilowanych przez aplikacje przeciwko Google.
Weryfikacja CTS zapewnia, że w przypadku każdej zadeklarowanej wersji interfejsów API rozszerzeń w wszystkie interfejsy API do tej wersji i jej poprzednich wersji są dostępne i działające.
Wydajność
Moduł rozszerzeń jest domyślnie zapisany w pamięci podręcznej w programach wczytujących klas systemu innych niż bootclasspath, począwszy od Androida 14 (poziom interfejsu API 34), dlatego nie ma wpływu na wydajność, ponieważ wczytuje się on do pamięci podczas uruchamiania aplikacji. Korzystanie z funkcji poszczególnych modułów może mieć niewielki wpływ na charakterystykę wydajności aplikacji, gdy między klientem a serwerem są wykonywane dodatkowe wywołania IPC.
Moduły
Umieszczanie aktywności
W sekcji Umieszczanie aktywności udostępnia zestaw funkcji, które umożliwiają aplikacjom porządkowanie prezentacji w oknie aktywności w granicach aplikacji nadrzędnej. Ten obejmuje wyświetlanie dwóch aktywności jednocześnie obok siebie w układ z kilkoma panelami, który umożliwia optymalizację dużego ekranu w przypadku starszych wersji aplikacji.
Komponent umieszczania aktywności musi być dostępny na wszystkich urządzeniach, które obsługują
z wbudowanym wyświetlaczem o rozmiarze równym sw600 dp
lub większym.
Umieszczanie aktywności musi być też włączone na urządzeniach obsługujących zewnętrzny wyświetlacz
połączeń, ponieważ aplikacja może być wyświetlana w większym rozmiarze,
gdy wyświetlacze są podłączone w czasie działania.
Konfiguracja urządzenia
Nie jest wymagana żadna konkretna konfiguracja urządzenia oprócz włączenia rozszerzeń zgodnie z opisem w sekcji Rozkład modułów rozszerzeń. . Warto włączyć rozszerzenia na wszystkich urządzeniach, które obsługują tryb wielu okien. W przyszłych wersjach Androida prawdopodobnie pojawią się rozszerzenia wymagane w popularnych konfiguracjach urządzeń przenośnych i urządzeń z dużym ekranem.
Informacje o układzie okien
Komponent informacji o układzie okna określa położenie i stan urządzenia składanego, gdy zawias przekracza okno aplikacji. Informacje o układzie okien umożliwiają aplikacjom reagowanie i wyświetlanie zoptymalizowane układy w trybie Na stole na urządzeniach składanych. Zobacz Informacje o widoczności reklam w aplikacji aby poznać szczegóły wykorzystania.
Składane urządzenia z Androidem wyposażone w zawias, który łączy oddzielne lub
panele z ciągłym ekranem muszą przekazywać informacje o zawiasie.
dostępne dla aplikacji do WindowLayoutComponent
.
Położenie i granice zawiasu muszą być zgłaszane w odniesieniu do aplikacji
okno identyfikowane przez interfejs Context
przekazany do interfejsu API. Jeśli okno aplikacji
te granice nie przecinają się z granicami zawiasu,
DisplayFeature
nie można zgłaszać. Dozwolone jest też niezgłaszanie funkcji wyświetlania
gdy pozycja firmy może nie być wiarygodna, na przykład gdy aplikacja
okno może dowolnie przenosić użytkownik w trybie wielu okien lub
trybu letterboxing.
W przypadku funkcji składania:
aktualizacje stanu muszą być zgłaszane, gdy zawias zmienia się między
wersji stabilnej. Domyślnie w stanie płaskiego interfejsu API interfejs API musi raportować
FoldingFeature.State.FLAT
Jeśli urządzenie może znajdować się w trybie złożonym do połowy w stabilnym stanie,
Interfejs API musi raportować dane: FoldingFeature.State.HALF_OPENED
.
W interfejsie API nie ma stanu zamkniętego, ponieważ w takim przypadku okno aplikacji
nie byłby widoczny lub nie przekraczałby granic zawiasów.
Konfiguracja urządzenia
Aby zapewnić obsługę implementacji funkcji składania, producenci OEM muszą wykonać te czynności:
Skonfiguruj stany urządzeń w usłudze
device_state_configuration.xml
, których ma używaćDeviceStateManagerService
ZobaczDeviceStateProviderImpl.java
.Jeśli domyślne implementacje
DeviceStateProvider
lubDeviceStatePolicy
nieodpowiednie dla danego urządzenia, można zastosować niestandardową implementację.Włącz moduł rozszerzeń zgodnie z opisem w sekcji Rozkład modułów rozszerzeń.
Określ lokalizację funkcji wyświetlania w
com.android.internal.R.string.config_display_features
zasób tekstowy (zwykle wframeworks/base/core/res/res/values/config.xml
w nakładce na urządzeniu).Oczekiwany format ciągu:
<type>-[<left>,<top>,<right>,<bottom>]
type
może mieć wartośćfold
lubhinge
. Wartości:left
,top
,right
ibottom
to współrzędne w pikselach w przestrzeni współrzędnych wyświetlania w do naturalnej orientacji wyświetlacza. Ciąg konfiguracji może zawierać wiele elementów funkcje wyświetlania rozdzielone średnikami.Na przykład:
<!-- Jetpack WindowManager display features --> <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
Określ mapowanie między wewnętrznymi identyfikatorami stanu urządzenia używanymi w
DeviceStateManager
oraz publiczne stałe stanowe wysyłane do deweloperów w:com.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:
COMMON_STATE_NO_FOLDING_FEATURES = 1
: w tym stanie nie ma funkcji składania, aby raport. Może to być na przykład stan zamknięty w typowym systemie składania tak, by ekran główny znajdował się od wewnątrz.COMMON_STATE_HALF_OPENED = 2
: funkcja zwijania jest otwarta w połowie.COMMON_STATE_FLAT = 3
: funkcja zwijania jest płaska. Może to być na przykład stan otwarty w typowym składanym urządzeniu, którego ekran główny jest od strony wewnętrznej.COMMON_STATE_USE_BASE_STATE = 1000
: w Android 14 – wartość, której można używać do emulacji w których stan zawiasu jest określany przy użyciu stanu podstawowego, zgodnie z definicjąCommonFoldingFeature.java
.
Więcej informacji:
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>
Obszar okna
Komponent obszaru okna zawiera zestaw funkcji, które umożliwiają aplikacjom dostęp do dodatkowych wyświetlaczy i obszarów na niektórych urządzeniach z wieloma wyświetlaczami.
Tryb tylnego wyświetlacza umożliwia aplikacji wyświetlanie interfejsu podglądu aparatu na na wyświetlaczu składanego urządzenia, który umożliwia korzystanie z aparatu głównego selfie i filmy. urządzeń zgodnych z Androidem, (zgodnie z definicją podaną w dokumencie CDD dla Androida w kontekście atrybutów, takich jak rozmiar, gęstość dostępne funkcje nawigacji) obejmują wyświetlacz, który dopasowuje się do tylnego urządzenia aparaty muszą zapewniać dostęp do trybu tylnego wyświetlacza.
W Androidzie 14 tryb podwójnego ekranu umożliwia aplikacjom, które działają na wewnętrznym ekranie urządzenia składanego, wyświetlanie na okładce dodatkowej zawartości skierowanej do innych użytkowników. na przykład na wyświetlaczu na okładce może być widoczny podgląd z aparatu osobie, która jest fotografowana lub nagrywana.
Konfiguracja urządzenia
Aby zapewnić obsługę implementacji funkcji składania, producenci OEM muszą wykonać te czynności:
Skonfiguruj stany urządzeń w usłudze
device_state_configuration.xml
, których ma używaćDeviceStateManagerService
ZobaczDeviceStateProviderImpl.java
.Jeśli domyślna implementacja
DeviceStateProvider
lubDeviceStatePolicy
nie jest odpowiedni dla danego urządzenia, można użyć niestandardowej implementacji.W przypadku urządzeń składanych, które obsługują tryb otwarty lub płaski, podaj odpowiednią wartość: w
com.android.internal.R.array.config_openDeviceStates
.W przypadku urządzeń składanych, które obsługują stan złożenia, podaj odpowiednie dane w
com.android.internal.R.array.config_foldedDeviceStates
.Urządzenia składane, które umożliwiają złożenie do połowy (zawias jest w połowie otwarty) np. laptopa), wymień odpowiednie stany w
com.android.internal.R.array.config_halfFoldedDeviceStates
Urządzenia obsługujące tryb tylnego wyświetlacza:
- Wyświetl odpowiednie stany w polu
com.android.internal.R.array.config_rearDisplayDeviceStates
dla:DeviceStateManager
. - Określ fizyczny wyświetlany adres tylnego wyświetlacza w polu
com.android.internal.R.string.config_rearDisplayPhysicalAddress
. - Określ identyfikator stanu w polu
com.android.internal.R.integer.config_deviceStateRearDisplay
, który ma być używany przez rozszerzenia. - Dodaj identyfikator stanu w
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests
, aby udostępnić go aplikacjom.
- Wyświetl odpowiednie stany w polu
W przypadku urządzeń z Androidem 14, które obsługują tryb podwójnego (równoczesnego) wyświetlania:
- Ustaw
com.android.internal.R.bool.config_supportsConcurrentInternalDisplays
natrue
. - Określ fizyczny wyświetlany adres tylnego wyświetlacza w polu
com.android.internal.R.config_deviceStateConcurrentRearDisplay
. - Określ identyfikator stanu w zasadzie
com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay
, który ma być używany przez rozszerzenia, jeśli ma być on dostępny dla aplikacji. - Dodaj identyfikator stanu w
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests
, aby udostępnić go aplikacjom.
- Ustaw
Weryfikacja
OEM musi zweryfikować swoje wdrożenia, aby zapewnić wspólne działanie oczekiwanego działania w różnych sytuacjach. Testy CTS i testy z użyciem Jetpack WindowManager są dostępne dla producentów OEM do testowania implementacji.
Testy CTS
Aby przeprowadzić testy CTS, zobacz Przeprowadzanie testów CTS. CTS
testów związanych z narzędziem Jetpack WindowManager znajduje się w lokalizacji cts/tests/framework/base/windowmanager/jetpack/
.
Nazwa modułu testowego to CtsWindowManagerJetpackTestCases
.
Testy WindowManager
Aby pobrać testy Jetpack WindowManager, wykonaj
Instrukcje dotyczące Androida Jetpacka
Testy znajdują się w bibliotece okien w module window:window
: window/window/src/androidTest/
.
Aby uruchomić testy urządzenia w module window:window
z poziomu wiersza poleceń,
następujące:
- Podłącz urządzenie z włączonymi opcjami programisty i debugowaniem USB.
- Zezwól komputerowi na debugowanie urządzenia.
- Otwórz powłokę w katalogu głównym repozytorium Androidax.
- Zmień katalog na
framework/support
. - Uruchom to polecenie:
./gradlew window:window:connectedAndroidTest
. - Przeanalizuj wyniki.
Aby uruchomić testy w Android Studio, wykonaj te czynności:
- Otwórz Android Studio.
- Podłącz urządzenie z włączonymi opcjami programisty i debugowaniem USB.
- Zezwól komputerowi na debugowanie urządzenia.
- Przejdź do testu w bibliotece okien w module okien.
- Otwórz zajęcia testowe i uruchom je, używając zielonych strzałek po prawej stronie redaktorem.
Możesz też utworzyć konfigurację w Android Studio, aby przeprowadzić test klasy testowej czy wszystkich testów w module.
Wyniki można analizować ręcznie, sprawdzając dane wyjściowe powłoki. Niektóre są pomijane, jeśli urządzenie nie spełnia określonych założeń. Wyniki to są zapisywane w standardowej lokalizacji, a analitycy mogą napisać skrypt analizy wyników.