Rozszerzenia WindowManager

Biblioteka Jetpack WindowManager umożliwia deweloperom aplikacji obsługę nowych formatów urządzeń i środowisk z wieloma oknami.

WindowManager Extensions (Extensions) 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łu Extensions

Rozszerzenia są kompilowane w bibliotece .jar i umieszczane w partycji system_ext na urządzeniu, jeśli są włączone w pliku makefile urządzenia.

Aby włączyć rozszerzenia na urządzeniu, dodaj te elementy do pliku makefile urządzenia:

$(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 oraz ustawienie właściwości persist.wm.extensions.enabled. Umieszczenie tych pakietów w pliku makefile powoduje też umieszczenie deklaracji w etc/permissions/, dzięki czemu są one dostępne dla procesów aplikacji. Zwykle moduły są wczytywane i wykonywane w ramach procesu aplikacji w czasie działania, gdy są używane przez bibliotekę Jetpack WindowManager. Dzięki temu ich działanie jest podobne do kodu frameworka po stronie klienta, jak pokazano na ilustracji poniżej:

Moduł androidx.window.extensions to aktualny moduł Extensions, nad którym trwają prace. Moduł androidx.window.sidecar to starszy moduł dołączony w celu zapewnienia zgodności z najwcześniejszymi wersjami Jetpack WindowManager, ale nie jest już aktywnie utrzymywany.

Ilustracja poniżej przedstawia logikę określania użycia androidx.window.extensions lub androidx.window.sidecar.

Moduły rozszerzeń

Rozszerzenia zapewniają funkcje okien na składanych urządzeniach z dużym ekranem i urządzeniach obsługujących okna na wyświetlaczach zewnętrznych. Obszary funkcji obejmują:

• Osadzanie aktywności
• Informacje o układzie okna
• Obszar okna

Implementacje rozszerzeń przez producentów OEM mogą udostępniać komponenty null lub komponenty z domyślnymi implementacjami albo implementacjami zastępczymi metod w WindowExtensions interfejsie, jeśli sprzęt urządzenia nie obsługuje odpowiednich funkcji, chyba że funkcja jest wyraźnie wymagana w dokumencie Compatibility Definition Document (CDD) 7.1.1.1.

Rozszerzenia i interfejsy Jetpack API

Moduł WindowManager Extensions udostępnia własny interfejs API oprócz publicznych interfejsów API platformy. Moduł Extensions jest opracowywany publicznie w bibliotece Jetpack androidx.window.extensions , która nie jest przeznaczona dla deweloperów, aby Jetpack WindowManager (androidx.window) mógł się z nią połączyć w czasie kompilacji. Interfejs API rozszerzeń zwykle udostępnia interfejsy API niższego poziomu.

Interfejsy API udostępniane przez rozszerzenia są przeznaczone tylko do użytku przez bibliotekę Jetpack WindowManager. Interfejsy API rozszerzeń nie są przeznaczone do bezpośredniego wywoływania przez deweloperów aplikacji. Aby zapewnić prawidłowe działanie, biblioteki rozszerzeń nie można dodać jako zależności aplikacji w pliku kompilacji Gradle. Unikaj bezpośredniego kompilowania biblioteki rozszerzeń w aplikacji. Zamiast tego korzystaj z wczytywania w czasie działania, aby zapobiec wczytywaniu mieszanki wstępnie skompilowanych i dostarczonych w czasie działania klas rozszerzeń.

Jetpack WindowManager (androidx.window) należy dodać jako zależność aplikacji. Udostępnia on publiczne interfejsy API dla deweloperów, w tym interfejsy API funkcji WindowManager Extensions. Biblioteka WindowManager automatycznie wczytuje rozszerzenia do procesu aplikacji i opakowuje interfejsy API rozszerzeń niższego poziomu w abstrakcje wyższego poziomu i bardziej ukierunkowane interfejsy. Interfejsy API Jetpack WindowManager są zgodne ze standardami nowoczesnego tworzenia aplikacji na Androida i mają zapewniać wygodną interoperacyjność dzięki dobrej integracji z bazami kodu, które korzystają z innych bibliotek AndroidX.

Wersje i aktualizacje rozszerzeń

Moduł Extensions można aktualizować wraz z platformą Android w ramach aktualizacji rocznych lub kwartalnych. Aktualizacje kwartalne umożliwiają zwiększanie poziomu interfejsu API rozszerzeń między aktualizacjami interfejsu API platformy Android, co pozwala na szybsze iteracje i daje producentom OEM możliwość dodania oficjalnego dostępu do interfejsu API do nowych funkcji zbliżonych do premier sprzętu.

Tabela poniżej zawiera listę wersji interfejsu API androidx.window.extensions dla różnych wersji Androida.

Poziom interfejsu API rozszerzeń (środkowa kolumna) jest zwiększany za każdym razem, gdy do istniejącego stabilnego interfejsu API (prawa kolumna) dodawana jest nowa funkcja.

Zgodność wsteczna i przyszła

Jetpack WindowManager radzi sobie ze złożonością związaną z częstymi aktualizacjami poziomu interfejsu API, szybkim rozwojem interfejsu API i zgodnością wsteczną. Gdy kod biblioteki jest wykonywany w procesie aplikacji, biblioteka sprawdza zadeklarowany poziom interfejsu API rozszerzeń i zapewnia dostęp do funkcji zgodnie z zadeklarowanym poziomem.

Aby chronić aplikację przed awarią w czasie działania, WindowManager przeprowadza też w czasie działania sprawdzenie dostępnych interfejsów API rozszerzeń za pomocą refleksji Java zgodnie z zadeklarowanym poziomem interfejsu API rozszerzeń. Jeśli wystąpi niezgodność, WindowManager może wyłączyć używanie rozszerzeń (częściowo lub całkowicie) i zgłosić, że odpowiednie funkcje są niedostępne dla aplikacji.

Rozszerzenia WindowManager są implementowane jako moduł system_ext, który używa prywatnych interfejsów API platformy do wywoływania rdzenia WindowManager, DeviceStateManager, i innych usług systemowych w implementacji funkcji rozszerzeń.

Zgodność może nie być zachowana w przypadku wersji rozszerzeń przedpremierowych przed odpowiednią kwartalną lub roczną wersją platformy Android, z którą wersje są finalizowane. Pełną historię interfejsów API rozszerzeń można znaleźć w plikach tekstowych interfejsu API w gałęzi wydania window:extensions:extensions.

Nowsze wersje rozszerzeń muszą nadal działać ze starszymi wersjami WindowManager skompilowanymi w aplikacjach, aby zachować zgodność przyszłą. Aby to zapewnić, każda nowa wersja interfejsu API rozszerzeń dodaje tylko nowe interfejsy API i nie usuwa starszych. Dzięki temu aplikacje ze starszymi wersjami WindowManager mogą nadal korzystać ze starszych interfejsów API rozszerzeń, z którymi zostały skompilowane.

Weryfikacja CTS zapewnia, że w przypadku każdej zadeklarowanej wersji interfejsów API rozszerzeń na urządzeniu wszystkie interfejsy API dla tej i poprzednich wersji są obecne i działają.

Wydajność

Moduł Extensions jest domyślnie buforowany w systemowych programach wczytujących klasy, które nie znajdują się na ścieżce rozruchowej, począwszy od Androida 14 (poziom interfejsu API 34). Dzięki temu wczytywanie 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 wydajność aplikacji, gdy między klientem a serwerem wykonywane są dodatkowe wywołania IPC.

Moduły

Osadzanie aktywności

Komponent osadzania aktywności umożliwia aplikacjom optymalizowanie interfejsu pod kątem urządzeń z dużym ekranem i wyświetlaczy zewnętrznych. Osadzanie aktywności umożliwia wyświetlanie 2 aktywności obok siebie w układzie wielopanelowym, co ułatwia tworzenie aplikacji adaptacyjnych dla starszych aplikacji.

Komponent osadzania aktywności musi być dostępny na wszystkich urządzeniach z wbudowanym wyświetlaczem o rozmiarze co najmniej sw600dp. Osadzanie aktywności musi być też włączone na urządzeniach obsługujących połączenia z wyświetlaczami zewnętrznymi, ponieważ aplikacja może być wyświetlana w większym rozmiarze, gdy wyświetlacze zewnętrzne są podłączone w czasie działania.

Konfiguracja urządzenia

Nie jest wymagana żadna specjalna konfiguracja urządzenia poza włączeniem modułu Extensions zgodnie z opisem w sekcji Dystrybucja modułu Extensions. Warto włączyć rozszerzenia na wszystkich urządzeniach obsługujących tryb wielu okien. W przyszłych wersjach Androida rozszerzenia będą prawdopodobnie wymagane w przypadku typowych konfiguracji 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 składanym urządzeniu, gdy zawias przecina okno aplikacji. Informacje o układzie okna umożliwiają aplikacjom reagowanie na składane urządzenia i wyświetlanie zoptymalizowanych układów w trybie stołowym. Szczegółowe informacje o użyciu znajdziesz w artykule Przygotowanie aplikacji na składane urządzenia.

Składane urządzenia z Androidem, które mają zawias łączący oddzielne lub ciągłe obszary panelu wyświetlacza, muszą udostępniać informacje o zawiasie aplikacjom za pomocą WindowLayoutComponent.

Położenie i granice zawiasu muszą być zgłaszane względem okna aplikacji zidentyfikowanego przez Context przekazany do interfejsu API. Jeśli granice okna aplikacji nie przecinają się z granicami zawiasu, nie można zgłaszać DisplayFeature zawiasu. Można też nie zgłaszać funkcji wyświetlania, gdy ich położenie może nie być zgłaszane wiarygodnie, np. gdy okno aplikacji może być swobodnie przenoszone przez użytkownika w trybie wielu okien lub w trybie letterboxingu zgodności.

W przypadku funkcji składania aktualizacje stanu muszą być zgłaszane, gdy położenie zawiasu zmienia się między stanami stabilnymi. Domyślnie w stanie płaskiego wyświetlacza interfejs API musi zgłaszać FoldingFeature.State.FLAT. Jeśli sprzęt urządzenia może pozostawać w stanie półzłożonym w stanie stabilnym, interfejs API musi zgłaszać FoldingFeature.State.HALF_OPENED. W interfejsie API nie ma stanu zamkniętego, ponieważ w takim przypadku okno aplikacji nie byłoby widoczne lub nie przecinałoby granic zawiasu.

Konfiguracja urządzenia

Aby obsługiwać implementację funkcji składania, producenci OEM muszą wykonać te czynności:

• Skonfiguruj stany urządzenia w device_state_configuration.xml, aby były używane przez DeviceStateManagerService. Informacje znajdziesz w DeviceStateProviderImpl.java.

  Jeśli domyślne implementacje DeviceStateProvider lub DeviceStatePolicy nie są odpowiednie dla urządzenia, można użyć implementacji niestandardowej.

• Włącz moduł Extensions zgodnie z opisem w sekcji Dystrybucja modułu Extensions.

• Określ lokalizację funkcji wyświetlania w zasobie tekstowym com.android.internal.R.string.config_display_features (zwykle w frameworks/base/core/res/res/values/config.xml w nakładce urządzenia).

  Oczekiwany format ciągu znaków:

  <type>-[<left>,<top>,<right>,<bottom>]

  Wartość type może być fold lub hinge. Wartości left, top, right i bottom to współrzędne pikseli w przestrzeni współrzędnych wyświetlacza w naturalnej orientacji wyświetlacza. Ciąg znaków konfiguracji może zawierać wiele funkcji wyświetlania rozdzielonych średnikami.

  Przykład:

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

• Zdefiniuj mapowanie między wewnętrznymi identyfikatorami stanu urządzenia używanymi w DeviceStateManager a publicznymi stałymi stanu wysyłanymi do deweloperów w com.android.internal.R.array.config_device_state_postures.

  Oczekiwany format każdego wpisu:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  Obsługiwane identyfikatory stanu:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: stan nie ma funkcji składania do zgłoszenia. Może to być np. stan zamknięty typowego urządzenia składanego do wewnątrz z ekranem głównym po wewnętrznej stronie.
  • COMMON_STATE_HALF_OPENED = 2: funkcja składania jest częściowo otwarta.
  • COMMON_STATE_FLAT = 3: funkcja składania jest płaska. Może to być np. stan otwarty typowego urządzenia składanego do wewnątrz z ekranem głównym po wewnętrznej stronie.
  • COMMON_STATE_USE_BASE_STATE = 1000: w Androidzie 14 wartość, której można używać w przypadku stanów emulowanych , w których stan zawiasu jest określany na podstawie stanu podstawowego, zgodnie z definicją w CommonFoldingFeature.java

  Więcej informacji znajdziesz w DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int).

  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 udostępnia zestaw funkcji, które zapewniają aplikacjom dostęp do dodatkowych wyświetlaczy i obszarów wyświetlania na niektórych składanych urządzeniach i urządzeniach z wieloma wyświetlaczami.

Tryb wyświetlania z tyłu umożliwia aplikacji wyświetlanie interfejsu podglądu z aparatu na wyświetlaczu zewnętrznym składanego urządzenia, co pozwala na używanie głównego aparatu urządzenia do robienia selfie i nagrywania filmów. Urządzenia, które mają wyświetlacz zewnętrzny zgodny z Androidem (zgodnie z definicją w dokumencie CDD Androida pod względem atrybutów takich jak rozmiar, gęstość i dostępne elementy nawigacyjne) i który jest wyrównany z tylnymi aparatami urządzenia, muszą zapewniać dostęp do trybu wyświetlania z tyłu.

W Androidzie 14 tryb podwójnego wyświetlania umożliwia aplikacjom działającym na wewnętrznym ekranie składanego urządzenia wyświetlanie dodatkowych treści na wyświetlaczu zewnętrznym skierowanym do innych użytkowników. Na przykład wyświetlacz zewnętrzny może wyświetlać podgląd z aparatu osobie fotografowanej lub nagrywanej.

Konfiguracja urządzenia

Aby obsługiwać implementację funkcji składania, producenci OEM muszą wykonać te czynności:

• Skonfiguruj stany urządzenia w device_state_configuration.xml, aby były używane przez DeviceStateManagerService. Więcej informacji znajdziesz w DeviceStateProviderImpl.java.

  Jeśli domyślna implementacja DeviceStateProvider lub DeviceStatePolicy nie jest odpowiednia dla urządzenia, można użyć implementacji niestandardowej.

• W przypadku składanych urządzeń 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 do wewnątrz, które obsługują stany złożone, wymień odpowiednie identyfikatory stanu w com.android.internal.R.array.config_foldedDeviceStates.

• W przypadku urządzeń składanych do wewnątrz, które obsługują stan półzłożony (zawias jest częściowo otwarty jak laptop), wymień odpowiednie stany w com.android.internal.R.array.config_halfFoldedDeviceStates.

• W przypadku urządzeń obsługujących tryb wyświetlania z tyłu:

  • Wymień odpowiednie stany w com.android.internal.R.array.config_rearDisplayDeviceStates dla DeviceStateManager.
  • Określ fizyczny adres wyświetlacza z tyłu w com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • Określ identyfikator stanu w 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 był dostępny dla aplikacji.

• W Androidzie 14 w przypadku urządzeń obsługujących tryb podwójnego (jednoczesnego) wyświetlania:

  • Ustaw com.android.internal.R.bool.config_supportsConcurrentInternalDisplays na true.
  • Określ fizyczny adres wyświetlacza z tyłu w com.android.internal.R.config_deviceStateConcurrentRearDisplay.
  • Określ identyfikator stanu w com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay, który ma być używany przez rozszerzenia, jeśli identyfikator ma być udostępniany aplikacjom.
  • Dodaj identyfikator stanu w com.android.internal.R.array.config_deviceStatesAvailableForAppRequests, aby był dostępny dla aplikacji.

Weryfikacja

Producenci OEM muszą zweryfikować swoje implementacje, aby zapewnić oczekiwane działanie w typowych scenariuszach. Producenci OEM mogą testować implementacje za pomocą testów CTS i testów z użyciem Jetpack WindowManager.

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 WindowManager

Aby pobrać testy Jetpack WindowManager, postępuj zgodnie z instrukcjami dotyczącymi Androida Jetpack. Testy znajdują się w bibliotece okien w module window:window: window/window/src/androidTest/.

Aby uruchomić testy urządzenia dla modułu window:window z wiersza poleceń:

1. Podłącz urządzenie, na którym włączono opcje dla programistów i debugowanie USB.
2. Zezwól komputerowi na debugowanie urządzenia.
3. Otwórz powłokę w katalogu głównym repozytorium androidx.
4. Zmień katalog na framework/support.
5. Uruchom to polecenie: ./gradlew window:window:connectedAndroidTest.
6. Przeanalizuj wyniki.

Aby uruchomić testy z Android Studio:

1. Otwórz Android Studio.
2. Podłącz urządzenie, na którym włączono opcje dla programistów i debugowanie USB.
3. Zezwól komputerowi na debugowanie urządzenia.
4. Otwórz test w bibliotece okien modułu okna.
5. Otwórz klasę testową i uruchom ją za pomocą zielonych strzałek po prawej stronie edytora.

Możesz też utworzyć konfigurację w Android Studio, aby uruchomić metodę testową, klasę testową lub wszystkie testy w module.

Wyniki można analizować ręcznie, sprawdzając dane wyjściowe powłoki. Niektóre testy są pomijane, jeśli urządzenie nie spełnia określonych założeń. Wyniki są zapisywane w standardowej lokalizacji, a analitycy mogą napisać skrypt, który zautomatyzuje analizę wyników.