Rozszerzenia WindowManager

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:

Rysunek 1. Rozszerzenia WindowManager wczytane do aplikacji podobny do kodu platformy.

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.

Rysunek 2. Drzewo decyzyjne dotyczące dostępu 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 directly; 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ń w Javie 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 modułach ładowania klas systemowych 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 Zobacz DeviceStateProviderImpl.java.

    Jeśli domyślne implementacje DeviceStateProvider lub DeviceStatePolicy 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 w frameworks/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 lub hinge. Wartości: left, top, right i bottom 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 Zobacz DeviceStateProviderImpl.java .

    Jeśli domyślna implementacja DeviceStateProvider lub DeviceStatePolicy 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.
    • Podaj 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.

  • 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 na true.
    • Podaj 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.

Weryfikacja

OEM musi zweryfikować swoje wdrożenia, aby zapewnić wspólne oczekiwane działanie 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:

  1. Podłącz urządzenie z włączonymi opcjami programisty i debugowaniem USB.
  2. Zezwól komputerowi na debugowanie urządzenia.
  3. Otwórz powłokę w katalogu głównym repozytorium Androidax.
  4. Zmień katalog na framework/support.
  5. Uruchom to polecenie: ./gradlew window:window:connectedAndroidTest.
  6. Przeanalizuj wyniki.

Aby uruchomić testy w Android Studio, wykonaj te czynności:

  1. Otwórz Android Studio.
  2. Podłącz urządzenie z włączonymi opcjami programisty i debugowaniem USB.
  3. Zezwól komputerowi na debugowanie urządzenia.
  4. Przejdź do testu w bibliotece okien w module okien.
  5. 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.