Ta strona została przetłumaczona przez Cloud Translation API.

Tryb zgodności urządzenia

Android aktywuje tryb zgodności w przypadku aplikacji, które deklarują ograniczenia dotyczące orientacji lub możliwości zmiany rozmiaru. Tryb zgodności zapewnia akceptowalne działanie aplikacji na urządzeniach z dużym ekranem i telefonach z klapką, ale z mniejszą funkcjonalnością.

Zastąpienia na poziomie aplikacji umożliwiają producentom urządzeń zmianę zachowania aplikacji w celu poprawy wrażeń użytkowników lub zapobiegania ich zepsuciu na określonych urządzeniach.

Urządzenia referencyjne

Na tych urządzeniach może być konieczne zastosowanie ustawień zastępczych dla poszczególnych aplikacji z powodu nietypowych konfiguracji lub konfiguracji, które nie są dobrze obsługiwane przez aplikacje:

Tablety: domyślna orientacja niektórych tabletów, takich jak Pixel Tablet, to orientacja pozioma. Urządzenie jest w naturalnej orientacji, gdy Display#getRotation() powraca do Surface.ROTATION_0. Jeśli aplikacje zakładają, że ROTATION_0 to orientacja pionowa, układy aplikacji i podgląd aparatu mogą nie pasować do ekranu urządzenia.
Składane urządzenia w orientacji poziomej: niektóre składane urządzenia, takie jak Pixel Fold, mają orientację pionową w sposobie zwykłego urządzenia, ale w orientacji poziomej po rozłożeniu. Jeśli aplikacje zakładają, że rozłożony ekran ma orientację pionową, mogą wystąpić problemy z migotaniem lub pętlami.
Składane telefony: rozłożone telefony są zwykle w orientacji pionowej. Jednak po złożeniu telefony zwykle mają mały ekran w orientacji poziomej. Aplikacje muszą wykrywać różne orientacje wyświetlacza i stosować się do nich.

Typowe problemy ze zgodnością

Najczęstsze problemy z kompatybilnością aplikacji wynikają z ograniczeń dotyczących orientacji aplikacji, możliwości zmiany rozmiaru i formatu obrazu, nieprawidłowego obsługi orientacji podglądu aparatu i niewłaściwego użycia interfejsów API.

Letterboxing

W trybie Letterbox aplikacja jest umieszczona na środku ekranu lub, w przypadku dużych ekranów, po jednej lub drugiej stronie, aby zapewnić wygodny dostęp. Nieużywane obszary wyświetlacza po bokach lub u góry i u dołu aplikacji wypełniają maty (kolorowe paski lub zamazane tapety).

Letterboxowanie często występuje na urządzeniach z dużym ekranem, ponieważ wymiary i format wyświetlacza różnią się od tych na standardowych telefonach, na które zaprojektowano większość aplikacji.

Rysunek 1. Aplikacja ograniczona do orientacji pionowej jest wyświetlana w formacie letterbox na tabletach i urządzeniach składanych w orientacji poziomej.

Problem

Aplikacja nie obsługuje wszystkich konfiguracji wyświetlania, ponieważ ma stałą orientację, stały współczynnik proporcji lub nie można jej zmienić rozmiaru.

Ustawienia konfiguracji, które kontrolują orientację i możliwość zmiany rozmiaru aplikacji:

screenOrientation: określa stałą orientację aplikacji. Aplikacje mogą też ustawiać orientację w czasie działania za pomocą elementu Activity#setRequestedOrientation().
resizeableActivity: wskazuje, czy system może zmieniać rozmiary aplikacji, aby pasowały one do okien o różnych wymiarach. W Androidzie 11 (poziom interfejsu API 30) lub starszym określa, czy aplikacje obsługują tryb wielookienkowy. W przypadku Androida 12 (poziom API 31) lub nowszego określa, czy aplikacje obsługują tryb wielookienkowy na małych ekranach (klasa rozmiaru okna). W systemie Android 12 i nowszych aplikacje obsługują tryb wielu okien na dużych ekranach (klasa rozmiaru okna średniego lub rozszerzonego) niezależnie od tego ustawienia.
maxAspectRatio: określa maksymalny współczynnik proporcji obsługiwany przez aplikację. Ustawienie maxAspectRatio mogą zmienić tylko aplikacje, w których parametrze resizeableActivity jest ustawiona wartość false.
minAspectRatio: określa minimalny format obrazu obsługiwany przez aplikację. Wartość minAspectRatio mogą ustawić tylko aplikacje, w których parametrze resizeableActivity jest ustawiona wartość false.

Aplikacja ograniczona do orientacji pionowej, nieużyteczna na urządzeniu w orientacji poziomej.

Optymalizacja

Aplikacja powinna obsługiwać wszystkie orientacje i rozmiary wyświetlacza oraz tryb wielookienności. Usuń wszystkie ograniczenia dotyczące orientacji i ustawionego formatu obrazu z pliku manifestu i schematów aplikacji.

Aplikacja obsługuje wszystkie orientacje urządzenia.

Sposób obejścia problemu z kompatybilnością

Jeśli aplikacja o niezmiennej orientacji lub współczynniku proporcji jest uruchamiana w oknie, które nie obsługuje bezpośrednio rozmiaru lub orientacji okna, Android umieszcza aplikację w ramce, aby zachować ciągłość.

Począwszy od Androida 12 (poziom API 31) i później 12L (poziom API 32), platforma wprowadza różne ulepszenia w aplikacji w formacie letterbox. Producenci urządzeń implementują ulepszenia interfejsu. Aby skorzystać z tych ulepszeń, nie musisz wprowadzać żadnych dodatkowych zmian w swojej aplikacji.

Android 12 (poziom interfejsu API 31) wprowadza te ulepszenia estetyczne, które mogą być konfigurowane przez producentów urządzeń:

Zaokrąglone rogi: rogi okna aplikacji mają bardziej wyrafinowany wygląd.
Przezroczystość paska systemu: paski stanu i paski nawigacyjne, które nakładają się na aplikację, są półprzezroczyste, dzięki czemu ikony na paskach są zawsze widoczne na tle letterbox.
Format obrazu: format obrazu aplikacji można dostosować, aby poprawić jej wygląd.

Rysunek 2. Aplikacja z letterboxem i ulepszona grafika.

12L (poziom interfejsu API 32) zawiera te ulepszenia funkcjonalności:

Możliwość konfiguracji położenia: na dużych ekranach producenci urządzeń mogą umieścić aplikację po lewej lub prawej stronie wyświetlacza, co ułatwia interakcję.
Zmieniony przycisk ponownego uruchamiania: producenci urządzeń mogą zmienić wygląd przycisku ponownego uruchamiania w trybie zgodności z rozmiarem, aby ułatwić użytkownikom jego rozpoznawanie.

Android 13 (poziom API 33) zawiera okno z informacjami dla użytkownika na temat umieszczania aplikacji w ramce na ekranie lub włączania ramki w trybie podzielonego ekranu:

Rysunek 3. Aplikacja w formacie letterbox z oknem z informacjami dla użytkowników

Tryb zgodności rozmiaru

Tryb zgodności z rozmiarem to format letterbox z opcją ponownego uruchamiania. Ten element sterujący umożliwia użytkownikom ponowne uruchomienie aplikacji i odświeżenie wyświetlacza. Android wywołuje tryb zgodności z rozmiarem w przypadku aplikacji, które nie mogą być zmieniane. Gdy aktywność zostanie przeniesiona do kontenera wyświetlania, który jest niezgodny z jej wymiarami, system może zmienić jej rozmiar, aby wypełnić co najmniej 1 wymiar ekranu urządzenia.

Zmiany konfiguracji urządzenia, które mogą spowodować uruchomienie trybu zgodności z rozmiarem:

Obracanie urządzenia
Składanie i rozkładanie składanego urządzenia
Przełączanie się między trybami wyświetlania pełnego ekranu i podzielonego ekranu

Problem

Tryb zgodności z rozmiarami jest zwykle stosowany w przypadku aktywności, które są ograniczone pod względem orientacji lub proporcji, a także skonfigurowane (lub określone przez system) tak, aby nie można było ich zmieniać.

Aplikacja jest uznawana za umożliwiającą zmianę rozmiaru i nie jest umieszczana w trybie zgodności z rozmiarem, jeśli spełnia co najmniej 1 z tych kryteriów:

można zmienić rozmiar za pomocą resizeableActivity="true",
Obsługuje tryb obrazu w obrazie (PIP).
jest umieszczony,
czy producent urządzenia zastosował zastąpienie FORCE_RESIZE_APP dla aplikacji (właściwości ustawione przez aplikację są ignorowane);

Jeśli Twoja aplikacja nie spełnia żadnego z tych warunków, jest uważana za nierozmiarową i może zostać umieszczona w trybie zgodności rozmiarów.

Aplikacja bez możliwości zmiany rozmiaru ulega awarii w trybie wielu okien.

Optymalizacja

Aplikacja powinna obsługiwać wszystkie rozmiary wyświetlania. Aby umożliwić zmianę rozmiaru aplikacji, ustaw atrybut android:resizeableActivity elementu <activity> lub <application> na true w pliku manifestu aplikacji. Zaprojektuj elastyczne lub adaptacyjne układy dla swojej aplikacji. Więcej informacji znajdziesz w artykułach Obsługa różnych rozmiarów wyświetlaczy i Obsługa trybu wielookiennego.

Aplikacja działa we wszystkich rozmiarach okien.

Sposób obejścia problemu z kompatybilnością

Android umieszcza aplikację w trybie zgodności z rozmiarem, gdy system stwierdzi, że wyświetlanie aplikacji w letterboxie można ulepszyć, zmieniając rozmiar aplikacji tak, aby wypełniała okno wyświetlania w przynajmniej 1 wymiarze. System wyświetla opcję ponownego uruchamiania, która ponownie tworzy proces aplikacji, odtwarza aktywność i ponownie rysuje wyświetlacz. Zobacz też omówienie procesów i wątków.

Aplikacja w orientacji pionowej w ramce w orientacji poziomej, z przeskalowaniem za pomocą elementu sterującego ponownym uruchamianiem.

migające pętle,

Jeśli aplikacja nie obsługuje wszystkich orientacji ekranu, może wielokrotnie prosić o nowe orientacje po zmianie konfiguracji, tworząc nieskończony cykl, który powoduje migotanie ekranu lub niekończące się obracanie aplikacji.

Problem

W Androidzie 12 (API na poziomie 31) i nowszych producenci urządzeń mogą skonfigurować swoje urządzenia tak, aby ignorowały ograniczenia orientacji określone przez aplikacje, a zamiast tego stosowały tryby zgodności. Na przykład urządzenie składane może zignorować ustawienie android:screenOrientation="portrait" aktywności, gdy jest ona wyświetlana na wewnętrznym ekranie w urządzeniu dotykowym w orientacji poziomej.

Jeśli ograniczenia orientacji aplikacji są ignorowane, aplikacja może ustawiać swoją orientację programowo, wywołując funkcję Activity#setRequestedOrientation(). Jeśli aplikacja nie obsługuje zmian konfiguracji (patrz Obsługa zmian konfiguracji), wywołanie powoduje jej ponowne uruchomienie. Po ponownym uruchomieniu aplikacja ponownie ignoruje ograniczenia orientacji, powtarza wywołanie funkcji setRequestedOrientation(), co powoduje ponowne uruchamianie aplikacji, i tak dalej w nieskończoności.

Może się to też zdarzyć, gdy naturalna orientacja (czyli zwykła, jak określa ją Android) ekranu urządzenia jest pozioma (czyli wywołanieDisplay#getRotation() zwracaSurface.ROTATION_0, gdy urządzenie ma format obrazu poziomego). Do tej pory aplikacje zakładały, że Display.getRotation() = Surface.ROTATION_0 oznacza, że urządzenie jest w orientacji pionowej, ale nie zawsze tak jest, na przykład na wewnętrznym ekranie niektórych składanych urządzeń i na niektórych tabletach.

Aplikacja w orientacji poziomej na składanym ekranie wewnętrznym może sprawdzić obrót ekranu, otrzymać wartość ROTATION_0, przyjąć, że naturalną orientacją urządzenia jest orientacja pionowa, i wywołać funkcję setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT ), aby zmienić układ aplikacji. Po ponownym uruchomieniu aplikacji (w orientacji poziomej) może ona ponownie sprawdzić obrót ekranu, otrzymać wartość ROTATION_0, wywołać funkcję setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT) i kontynuować nieskończoną pętlę.

Aplikacja przeznaczona tylko do wyświetlania w orientacji poziomej, gdy wyświetlacz jest w orientacji pionowej, wielokrotnie wywołuje `Activity#setRequestedOrientation()`.

Optymalizacja

Aplikacje nie mogą:

Ustaw domyślny kierunek za pomocą Activity#setRequestedOrientation() w metodzie activity onCreate(), ponieważ żądanie dotyczące orientacji może zostać nieoczekiwanie wywołane przez nieobsługiwane zmiany konfiguracji.
Zakładamy, że naturalna orientacja urządzenia (ROTATION_0) to orientacja pionowa
Ustaw orientację na podstawie sygnałów niezwiązanych z obecnym rozmiarem okna, takich jak Display#getRotation(), obecność FoldingFeature lub wycofane interfejsy API.

Aplikacja obsługuje zmianę konfiguracji, nie ma ograniczeń orientacji, więc nie wchodzi w pętlę migotania.

Sposób obejścia problemu z kompatybilnością

Android ignoruje wywołania funkcji Activity#setRequestedOrientation() w tych sytuacjach:

Aktywność została już ponownie uruchomiona po poprzednim wywołaniu metody lub włączono wymuszenie obracania w ramach obsługi zgodności z kamerą (patrz Podgląd kamery poniżej).

Producenci urządzeń mogą zastosować to zachowanie w przypadku aplikacji z OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION.
Aktywność wysłała w ciągu 1 sekundy więcej niż 2 żądania orientacji, co wskazuje na wystąpienie pętli. Z 2 żądań w pętli Android używa tego, które maksymalizuje obszar wyświetlania aplikacji.

Producenci urządzeń mogą zastosować to zachowanie w przypadku aplikacji z OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED.

Podgląd z aparatu

Podgląd aparatu (lub wizjer) w aplikacjach aparatu może być niewłaściwie wyrównany lub zniekształcony na tabletach, laptopach i ekranach składanych.

Problem

Dokument z definicją zgodności Androida stwierdza, że czujnik obrazu aparatu „MUSI być ustawiony tak, aby dłuższy wymiar aparatu był zgodny z dłuższym wymiarem ekranu”.

Aplikacje często zakładają, że orientacja urządzenia i czujnika aparatu jest pionowa – jest to rozsądne założenie w przypadku standardowych telefonów komórkowych. Jednak naturalna orientacja tabletów i laptopów oraz ich czujników aparatu może być pozioma. Ponadto nowe formaty, takie jak urządzenia składane, mogą mieć wiele naturalnych orientacji i wiele czujników aparatu w różnych orientacjach.

Rozpoczynanie aktywności z orientacją aparatu, której aplikacja nie obsługuje, lub przełączanie się między różnymi kamerami lub ekranami urządzenia (w przypadku składanych urządzeń) może spowodować przesunięcie lub zniekształcenie podglądu aparatu.

Nieprawidłowo wyrównany i zniekształcony podgląd z aparatu na składanym urządzeniu z dużym ekranem

Optymalizacja

Aplikacje do obsługi aparatu muszą prawidłowo rozpoznawać orientację urządzenia i czujnika aparatu oraz zarządzać nimi, aby wyświetlać prawidłowo wyrównany i przeskalowany podgląd aparatu. Aplikacje muszą obliczyć obrót urządzenia, obrót czujnika oraz współczynnik proporcji ekranu lub okna, a następnie zastosować wyniki w podglądzie aparatu. Szczegółowe wskazówki znajdziesz w artykułach Podgląd z aparatu i Wprowadzenie do wizjeru kamery.

Podgląd aparatu jest prawidłowo wyrównany i powiększony we wszystkich orientacjach urządzenia.

Sposób obejścia problemu z kompatybilnością

Urządzenie jest w naturalnej orientacji, gdy Display#getRotation() zwraca Surface.ROTATION_0. System oblicza CameraCharacteristics.SENSOR_ORIENTATIONna podstawie naturalnej orientacji urządzenia. Android dopasowuje okno pionowe aplikacji z ograniczeniami do naturalnej orientacji urządzenia, co jest wymagane przez większość aplikacji. Android przycina też obraz z czujnika aparatu, gdy orientacja czujnika jest pozioma, a podgląd aparatu – pionowa. Do tych obejść można zaliczyć:

Wymuszanie obracania podglądów aparatu w przypadku aplikacji ograniczonych do orientacji pionowej: aplikacje ograniczone do orientacji pionowej oczekują, że naturalna orientacja urządzenia i orientacja czujnika aparatu będą pionowe. W Androidzie 12 (poziom interfejsu API 31) i nowszych aplikacje mogą działać w różnych orientacjach, jeśli producenci urządzeń ignorują specyfikację orientacji.

Gdy aplikacja z ograniczeniami dotyczącymi orientacji pionowej jest połączona z aparatem, Android wymusza jej obrócenie, aby dopasować okno aplikacji do naturalnej orientacji urządzenia.

Na niektórych tabletach (patrz urządzenia referencyjne) okno aplikacji w orientacji pionowej jest obracane do pełnego ekranu w orientacji pionowej, aby dopasować je do naturalnej orientacji urządzenia. Po wymuszeniu obracania aplikacja zajmuje cały ekran.

Tablet – wymuszenie obracania aplikacji ograniczonej do orientacji pionowej.

Na wewnętrznym ekranie w orientacji poziomej składanych urządzeń (patrz urządzenia referencyjne) aktywności przeznaczone tylko do trybu pionowego są obracane w poziom, aby dopasować je do naturalnej orientacji po rozłożeniu. Aplikacja jest wyświetlana w formacie letterbox po wymuszonej rotacji.

składany – wymuszenie obracania aplikacji ograniczonej do orientacji pionowej. Aplikacja jest też wyświetlana w letterboxie.

Uwaga: wymuszanie obracania nie nastąpi, jeśli aplikacja jest elastyczna i obsługuje orientację poziomą i pionową.
Przycinanie wewnętrznego aparatu przedniego: w przypadku niektórych składanych urządzeń czujnik wewnętrznego aparatu przedniego jest w orientacji poziomej. Oprócz wymuszenia obracania podglądu aparatu na składanym wyświetlaczu wewnętrznym Android przycina pole widzenia wewnętrznego aparatu przedniego (w orientacji poziomej), aby czujnik rejestrował obraz przeciwny do orientacji urządzenia.
Wymuszanie odświeżania podglądów kamery: po wymuszonej rotacji system przechodzi przez metody aktywności onStop() i onStart() (domyślnie) lub onPause() i onResume() (stosowane przez zastąpienie OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE na poziomie aplikacji), aby upewnić się, że podgląd kamery jest prawidłowo wyświetlany.
Skalowanie formatu obrazu: system dynamicznie zmienia format obrazu wymuszonego obrotu kamery na większy minimalny format obrazu, co zapewnia prawidłowe skalowanie podglądu kamery.

Deweloperzy aplikacji mogą zignorować te obejścia, jeśli ich aplikacje obsługują podgląd aparatu. Zobacz zastąpienia na poziomie aplikacji.

Interfejsy API, których użytkownicy często nadużywają

Ponieważ Android obsługuje teraz takie funkcje jak tryb wielozadaniowości i urządzenia składane, wycofane zostały starsze interfejsy API i zastąpione nowszymi, które działają na wszystkich rozmiarach ekranów i w różnych formach urządzeń. Wycofane interfejsy API są jednak nadal dostępne ze względu na zgodność wsteczną.

Niektóre interfejsy API View są przeznaczone do specjalnych celów, które nie zawsze są dobrze rozumiane przez deweloperów.

Problem

Deweloperzy nadal używają wycofanych interfejsów API Display i nieprawidłowo zakładają, że interfejsy API zwracają granice aplikacji zamiast granic obszaru wyświetlania urządzenia. Może też być tak, że deweloperzy używają interfejsów API widoku do celów specjalnych, aby uzyskać ogólne dane wyświetlania. W efekcie po zmianie rozmiaru okna aplikacji dochodzi do błędów w przemieszczaniu elementów interfejsu, co powoduje problemy z układem.

Wycofane i często niewłaściwie używane interfejsy Display API:

Więcej informacji znajdziesz w artykule Obsługa trybu wielookiennego.

Nieprawidłowe użycie interfejsów API wyświetlania:

Wycofany interfejs API błędnie oblicza granice aplikacji. Treści aplikacji znikają z ekranu.

Optymalizacja

Nigdy nie licz na to, że rozmiar fizycznego wyświetlacza wystarczy do pozycjonowania elementów interfejsu. Przeprowadź migrację aplikacji na interfejsy API oparte na WindowMetrics, w tym na te interfejsy WindowManager:

Interfejs API poprawnie oblicza dane okna aplikacji.

Sposób obejścia problemu z kompatybilnością

2 zastąpienia dostosowują przestarzałe interfejsy API Display i niewłaściwie używane interfejsy API View, aby zwracać granice aplikacji: ALWAYS_SANDBOX_DISPLAY_APIS dla interfejsów API Display; OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS dla interfejsów API View. ALWAYS_SANDBOX_DISPLAY_APIS jest też domyślnie stosowany w przypadku aplikacji, które kwalifikują się do trybu zgodności z rozmiarem.

przejrzyste działania

Przezroczyste działania są wynikiem przezroczystych stylów tła, na przykład:

<style name="Transparent" parent="AppTheme">
    <item name="android:windowIsTranslucent">true</item>
    <item name="android:windowBackground">@android:color/transparent</item>
</style>

Tematy związane z dialogami, takie jak Theme.MaterialComponents.Dialog, mogą zawierać style, które czynią działania przejrzystymi.

Aktywności przezroczyste nie obejmują całej dostępnej przestrzeni wyświetlania, co utrudnia ich zarządzanie, ponieważ dostępna powierzchnia wyświetlania może się zmieniać w zależności od zmian konfiguracji, takich jak obracanie urządzenia, składanie i rozkładanie urządzenia oraz tryb wielookienkowy.

Problem

Przeźroczysta aktywność powinna być zgodna z granicami pierwszej nieprzezroczystej aktywności poniżej niej w stosie działań zadania. Jednak nieprzejrzysta aktywność, która uruchamia okno z prośbą o przyzwolenie, może być trampoline (czyli aktywnością, która uruchamia inną aktywność, a potem znika). W związku z tym system nie może określić granic aktywności trampoline, która uruchomiła przejrzystą aktywność z prośbą o przyzwolenie.

Dialog został nieprawidłowo umieszczony, ponieważ aktywność została uruchomiona z trampoliny.

Optymalizacja

Aktywności przejrzyste dziedziczą ograniczenia od najbardziej nieprzezroczystej aktywności znajdującej się poniżej nich w zestawie aktywności zadania. Nieprzezroczysta aktywność musi być dostępna przez cały cykl życia przejrzystej aktywności, od jej utworzenia do usunięcia. Z tego powodu nie wysyłaj próśb o udzielenie uprawnień z aktywności na trampolinie.

Jeśli aktywność trampoliny uruchamia prośbę o przyznanie uprawnień, użytkownik może nie widzieć okna dialogowego z prośbą o przyznanie uprawnień, ponieważ aktywność trampoliny zostanie zniszczona, zanim użytkownik zdąży odpowiedzieć na prośbę, a wymiary i położenie okna dialogowego mogą zostać obliczone niepoprawnie.

Aplikacje powinny zawsze wysyłać prośby o uprawnienia z działań, które pozostają widoczne, dopóki użytkownik nie podejmie decyzji.

Zaokrąglone narożniki

Aktywność może być przezroczysta, ponieważ styl określa przezroczystość tła lub dlatego, że zawartość aktywności nie wypełnia dostępnej przestrzeni wyświetlania. Jeśli przezroczysta aktywność wypełnia dostępną przestrzeń na ekranie, system automatycznie zaokrągla rogi tej aktywności, jeśli producent urządzenia skonfigurował ją w ten sposób. Jeśli jednak przezroczysta czynność (np. okno z prośbą o zgodę) nie wypełnia dostępnej przestrzeni, to od Ciebie zależy, czy zastosować zaokrąglone rogi.

Dialogi z prośbą o uprawnienia nie wypełniają dostępnej przestrzeni wyświetlania, ponieważ ich układ zwykle używa LayoutParams.WRAP_CONTENT zamiast LayoutParams.MATCH_PARENT.

Okno z zaokrąglonymi rogami prawidłowo umieszczone nad widoczną aktywnością uruchamiania.

Sposób obejścia problemu z kompatybilnością

Zachowaj widoczność działań, które uruchamiają działania dialogowe, do momentu, gdy użytkownik odpowie na dialog.

System zapewnia, że przezroczysta aktywność dziedziczy wszystkie ograniczenia od pierwszej nieprzezroczystej aktywności poniżej przezroczystej aktywności w grupie aktywności, w tym ograniczenia związane z:

Tryb zgodności rozmiaru
Orientacja
Format obrazu

Gry w Unity

Gry Unity działają na Androidzie w trybie pełnoekranowym lub wielooknowym. Jednak wiele gier w Unity traci na chwilę fokus i przestaje wyświetlać treści, gdy aplikacja jest w trybie wielookiennym.

Problem

W wersji Unity 2019.4 dodano opcję Resizable Window, aby umożliwić korzystanie z trybu wielookiennego na Androidzie. Jednak początkowa implementacja nie reagowała prawidłowo na cykl życia aktywności w trybie wielookiennym, przez co UnityPlayer zawieszał odtwarzanie, gdy aplikacja traciła fokus. Gracz renderuje czarny ekran lub ostatnią zamrożoną klatkę gry. Rozgrywka wznawia się dopiero wtedy, gdy użytkownik dotknie ekranu. Ten problem występuje w przypadku wielu aplikacji korzystających z silnika Unity, które w trybie wielookiennym wyświetlają się jako czarne okna.

Gra traci fokus w trybie wielu okien i renderuje się jako czarne okno.

Optymalizacja

Uaktualnij Unity do wersji 2019.4.40 lub nowszej i ponownie wyeksportuj grę. Pozostaw zaznaczoną opcję Resizable Window w ustawieniach odtwarzacza Androida, w przeciwnym razie gra zostanie wstrzymana, gdy nie będzie aktywna, mimo że będzie w pełni widoczna w trybie wielookiennym.

Gra prawidłowo renderuje treści w trybie wielu okien, nawet jeśli nie jest w centrum uwagi.

Sposób obejścia problemu z kompatybilnością

Producenci urządzeń mogą stosować zastąpienie OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS na poziomie aplikacji, aby zapewnić fałszywe zdarzenie focus w aplikacji w trybie wielozadaniowym. Zastąpienie umożliwia ponowne narysowanie zawartości i uniemożliwia jej przyciemnienie.

Testowanie aplikacji pod kątem problemów ze zgodnością

Aby przetestować aplikację i sprawdzić, jak działa na różnych formatach, skorzystaj z tych zasobów:

Strumieniowanie danych z urządzeń:aby przetestować aplikację na urządzeniach produkcyjnych (w tym na urządzeniach referencyjnych) hostowanych w centrach danych Google, zapoznaj się z artykułem Strumieniowanie danych z urządzeń z Androidem z użyciem Firebase .
Emulatory w Android Studio Hedgehog: informacje o tworzeniu emulatorów urządzeń referencyjnych znajdziesz w artykule Tworzenie urządzeń wirtualnych i zarządzanie nimi.
Emulator Android Studio z możliwością zmiany rozmiaru: informacje o dostępie do urządzeń wirtualnych znajdziesz w artykule Uruchamianie aplikacji w emulatorze Androida.

jest w formacie letterbox,

Sprawdź, czy każda aktywność może używać całej przestrzeni wyświetlania dostępnej dla aplikacji. Najpierw zadeklaruj w folderze testowym następujący kod:

Kotlin

fun Activity.isLetterboxed() : Boolean {
    if (isInMultiWindowMode) return false

    val wmc = WindowMetricsCalculator.getOrCreate()
    val currentBounds = wmc.computeCurrentWindowMetrics(this).bounds
    val maxBounds = wmc.computeMaximumWindowMetrics(this).bounds

    val isScreenPortrait = maxBounds.height() > maxBounds.width()

    return if (isScreenPortrait) {
        currentBounds.height() < maxBounds.height()
    } else {
        currentBounds.width() < maxBounds.width()
    }
}

Java

public boolean isLetterboxed(Activity activity) {
    if (activity.isInMultiWindowMode()) {
        return false;
    }

    WindowMetricsCalculator wmc = WindowMetricsCalculator.getOrCreate();
    Rect currentBounds = wmc.computeCurrentWindowMetrics(activity).getBounds()
    Rect maxBounds = wmc.computeMaximumWindowMetrics(activity).getBounds();

    boolean isScreenPortrait = maxBounds.height() > maxBounds.width();

    return (isScreenPortrait)
        ? currentBounds.height() < maxBounds.height()
        : currentBounds.width() < maxBounds.width();
}

Następnie przeprowadź test, aby sprawdzić, czy działanie jest prawidłowe i czy aktywność docelowa nie jest otoczona ramką:

Kotlin

@get:Rule
val activityRule = ActivityScenarioRule(MainActivity::class.java)

@Test
fun activity_launched_notLetterBoxed() {
    activityRule.scenario.onActivity {
        assertThat(it.isLetterboxed()).isFalse()
    }
}

Java

@Rule
public ActivityScenarioRule<MainActivity> rule = new ActivityScenarioRule<>(MainActivity.class);

public void activity_launched_notLetterBoxed() {
    try (ActivityScenario<MainActivity> scenario = ActivityScenario.launch(MainActivity.class)) {
        scenario.onActivity(activity -> {
            assertThat(isLetterboxed(activity)).isFalse();
        });
    }
}

Najlepiej przeprowadzać tego typu testy tylko do momentu, gdy aplikacja przejdzie go pomyślnie i udowodni, że jej aktywności zajmują całą dostępną przestrzeń wyświetlania. Przetestuj aplikację na wszystkich typach urządzeń, aby zapewnić spójne działanie.

Zastąpienia na poziomie aplikacji

Android udostępnia zastąpienia, które zmieniają skonfigurowane zachowanie aplikacji. Na przykład wartość zastąpienia FORCE_RESIZE_APP informuje system, aby pominąć tryb zgodności z rozmiarem i zmienić rozmiar aplikacji, tak aby pasowała do wymiarów wyświetlacza, nawet jeśli w manifeście aplikacji jest określona wartość resizeableActivity="false".

Producenci urządzeń stosują zastąpienia w wybranych aplikacjach lub we wszystkich aplikacjach na określonych urządzeniach z dużym ekranem. W Androidzie 14 (poziom interfejsu API 34) i nowszych użytkownicy mogą stosować zastąpienia w aplikacjach za pomocą ustawień urządzenia.

Zastępowanie użytkownika w poszczególnych aplikacjach

W Androidzie 14 i nowszych użytkownicy mogą zmieniać format obrazu aplikacji w menu ustawień. Menu jest dostępne na urządzeniach z dużym ekranem, takich jak urządzenia referencyjne.

Menu zawiera listę wszystkich aplikacji zainstalowanych na urządzeniu. Użytkownicy wybierają aplikację, a następnie ustawiają jej format obrazu na 3:4, 1:1, pełny ekran lub inną wartość skonfigurowaną przez producenta urządzenia. Użytkownicy mogą też zresetować format obrazu do domyślnego, który jest określony w pliku manifestu aplikacji.

Aplikacje mogą zrezygnować z zastąpienia zgodności, ustawiając te tagi PackageManager.Property:

PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE

Aby zrezygnować z zastąpienia zgodności z formatem obrazu użytkownika, dodaj właściwość do pliku manifestu aplikacji i ustaw jej wartość na false:
```
<application>
    <property
        android:name="android.window.
        PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE"
        android:value="false" />
</application>
```
Aplikacja zostanie wykluczona z listy aplikacji w ustawieniach urządzenia. Użytkownicy nie będą mogli zmienić formatu obrazu aplikacji.

Ustawienie tej właściwości na true nie ma żadnego wpływu.
PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE

Aby zrezygnować z opcji pełnoekranowego formatu obrazu w ramach zastąpienia zgodności z formatem obrazu użytkownika, dodaj właściwość do pliku manifestu aplikacji i ustaw jej wartość na false:
```
<application>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE"
        android:value="false" />
</application>
```
Opcja pełnego ekranu zostaje usunięta z listy opcji formatu obrazu w ustawieniach urządzenia. Użytkownicy nie będą mogli zastosować zastąpienia pełnoekranowego w Twojej aplikacji.

Uwaga: jeśli parametr PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE ma wartość false, ta właściwość nie ma wpływu.

Ustawienie tej właściwości na true nie ma żadnego wpływu.

Zoptymalizuj aplikację pod kątem wszystkich ekranów: nie ustawiaj ograniczeń współczynnika proporcji w aplikacji. Użyj klas rozmiarów okien, aby obsługiwać różne układy na podstawie dostępnej przestrzeni wyświetlania.

Zastąpienia producenta urządzenia według aplikacji

Producenci urządzeń stosują zastąpienia na poziomie aplikacji na wybranych urządzeniach. Urządzenia referencyjne mogą domyślnie stosować niektóre zastąpienia do różnych aplikacji.

Aplikacje mogą zrezygnować z większości zastąpień (patrz tabela Zastąpienia na poziomie aplikacji poniżej).

Za pomocą platformy zgodności możesz przetestować aplikację z włączonymi lub wyłączonymi zastąpieniami (patrz Narzędzia platformy zgodności). Po włączeniu zastąpienia są stosowane do całej aplikacji.

Możesz też użyć Android Debug Bridge (adb), aby włączyć lub wyłączyć zastąpienia i określić, które zastąpienia mają zastosowanie do Twojej aplikacji.

Włącz lub wyłącz zastąpienia w ten sposób:

adb shell am compat enable/disable <override name/id> <package>

W przypadku urządzeń referencyjnych sprawdź, które zastąpienia mają zastosowanie do Twojej aplikacji:

adb shell dumpsys platform_compat | grep <package name>

Tabela poniżej zawiera listę dostępnych zastąpień oraz wskazówki, jak zoptymalizować aplikację, aby nie musiała ona korzystać z zastąpień. Możesz dodać do pliku manifestu aplikacji flagi właściwości, aby zrezygnować z niektórych zastąpień.

Zastąpienia na poziomie aplikacji
Typ	Nazwa	ID	Opis
Możliwość zmiany rozmiaru	FORCE_RESIZE_APP	174042936	Ominięcie trybu zgodności z rozmiarem w przypadku aplikacji po zmianach konfiguracji.
	FORCE_NON_RESIZE_APP	181136395	Wymusza tryb zgodności z rozmiarem strony w przypadku zmian konfiguracji.
Format obrazu	OVERRIDE_MIN_ASPECT_RATIO	174042980	Zastąpienie w Gatekeeper, które musi być włączone, aby zastosować inne zastąpienia formatu obrazu.
	OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY	203647190	Jeśli ta opcja jest włączona (domyślnie), ograniczenia zastępują zakres tylko do aktywności w orientacji pionowej.
	OVERRIDE_MIN_ASPECT_RATIO_MEDIUM	180326845	Zmień minimalny format obrazu na 3:2.
	OVERRIDE_MIN_ASPECT_RATIO_LARGE	180326787	Zmień minimalny format obrazu na 16:9.
	OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN	208648326	Zmienia minimalny format obrazu, aby pasował do 50% rozmiaru ekranu (lub formatu obrazu na podzielonym ekranie).
	OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN	218959984	Wyłącza minimalne zastąpienie współczynnika proporcji, aby aplikacje były wyświetlane na pełnym ekranie w orientacji pionowej.
Orientacja	OVERRIDE_ANY_ORIENTATION	265464455	Umożliwia zastąpienie dowolnej orientacji.
	OVERRIDE_ANY_ORIENTATION_TO_USER	310816437	Zastępuje ustawienia orientacji, możliwość zmiany rozmiaru i ograniczenia dotyczące formatu obrazu.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT	265452344	Zastępuje orientację pionową, gdy aktywność ma nieokreśloną orientację.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR	265451093	Zastępuje orientację `nosensor` (użyj naturalnej orientacji urządzenia) wtedy, gdy aktywność ma nieokreśloną orientację.
	OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE	266124927	Obróci aplikacje tylko w układzie poziomym o 180 stopni.
	OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA	265456536	Ogranicza zakres zastępowania orientacji do sytuacji, gdy aplikacja jest połączona z kamerą.
	OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION	255940284	Gdy zadanie jest wyświetlane na pełnym ekranie (w tym w trybie letterbox), wyświetlacz ustawia się na stałą orientację poziomą.
	OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION	254631730	Ignoruje żądania dotyczące orientacji z aplikacji, aby uniknąć nieskończonych pętli obracania.
	OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED	273509367	Ignoruje powtarzające się żądania orientacji podczas ponownego uruchamiania aktywności. Jeśli Android wykryje, że aplikacja w ciągu 1 sekundy prosi o co najmniej 2 nowe orientacje, system uzna to za nieskończony cykl obracania i zastosuje zastąpienie.
	OVERRIDE_RESPECT_REQUESTED_ORIENTATION	236283604	Zapobiega letterboxingowi, wyłączając ustawienie ignorowania prośby o orientację przez producenta urządzenia.
Interfejsy API piaskownicy	NEVER_SANDBOX_DISPLAY_APIS	184838306	Zapobiega zmianie działania interfejsów API wyświetlania.
	ALWAYS_SANDBOX_DISPLAY_APIS	185004937	Wymusza, aby interfejsy API `Display` w aplikacji zwracały granice aplikacji. Interfejsy API `Display` zwracają logiczne granice obszaru wyświetlania, ale czasami aplikacja zakłada, że interfejsy API `Display` zwracają granice aplikacji, co prowadzi do problemów z interfejsem użytkownika.
	OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS	237531167	Wymusza na interfejsach API `View` używanych w aplikacji zwracanie granic aplikacji. Interfejsy API `View` zwracają logiczne granice obszaru wyświetlania, ale czasami aplikacja zakłada, że interfejsy API `View` zwracają granice aplikacji, co prowadzi do problemów z interfejsem użytkownika.
Zgodność z aparatem	OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION	263959004	Wyłącza przymusową rotację. Domyślnie wszystkie aplikacje aparatu z ustawionymi orientacjami są wymuszająco obracane, gdy otwarta jest podgląd aparatu.
	OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH	264304459	Usuwa domyślne twarde odświeżanie stosowane, gdy podgląd aparatu jest wymuszająco obracany.
	OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE	264301586	Przełącza twarde odświeżanie na miękkie odświeżanie, gdy podgląd aparatu jest wymuszająco obracany, co pomaga zachować stan podczas wymuszonej rotacji. Domyślnie Android stosuje odświeżanie twarde, gdy podgląd aparatu jest wymuszająco obracany. Twarde odświeżenie może spowodować problemy z utratą stanu aplikacji lub ich zaciemnienie, w zależności od tego, jak aplikacje zapisały poprzedni stan.
	OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT	250678880	Przycina bufor obrazu z wewnętrznego przedniego aparatu. Jeśli zastąpienie jest wyłączone, przycinanie wewnętrznego przedniego aparatu zostanie usunięte, a pole widzenia podglądu aparatu zostanie powiększone. Domyślnie na niektórych składanych urządzeniach (patrz urządzenia referencyjne) system przycina podgląd aparatu we wszystkich aplikacjach do obsługi aparatu, gdy używany jest przedni aparat wewnętrzny.
Różne	OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS	263259275	Zapobiega zaciemnianiu aplikacji, gdy traci ona fokus w trybie podzielonego ekranu. Aplikacja czeka na skupienie uwagi przed wyświetleniem treści, co może spowodować jej zawieszenie lub przyciemnienie. Zastąpienie umożliwia Androidowi wysłanie do aplikacji fałszywego zdarzenia dotyczącego stanu fokusu, które sygnalizuje aplikacji, że ma ponownie wyświetlać treści.

FORCE_RESIZE_APP

Wymusza możliwość zmiany rozmiaru pakietów, do których zastosowano zastąpienie. Nie wpływa na to, czy aplikacja może być uruchamiana w trybie wielookiennym, ale pozwala jej zmieniać rozmiar bez przechodzenia w tryb zgodności z rozmiarem ekranu.

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

W pliku manifestu aplikacji ustaw atrybut android:resizeableActivity na true. Aby umożliwić zmianę rozmiaru przy wyłączonym trybie wielookiennym za pomocą android:resizeableActivity=false, ustaw flagę metadanych android.supports_size_changes na true.

Optymalizacja aplikacji

Używaj układów elastycznych, aby umożliwić aplikacjom dostosowanie się do wszystkich rozmiarów i współczynników proporcji ekranu. Zapoznaj się z artykułem Obsługa różnych rozmiarów wyświetlania.

Jak wyłączyć lub zrezygnować z zastąpienia

Ustaw flagę właściwości PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES na false.

Flagi usług, które można dostosować do zastępowania

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

Polecenia adb do testowania zastąpienia

Aby zastosować zastąpienie i umożliwić zmianę rozmiaru aplikacji:

adb shell am compat enable FORCE_RESIZE_APP <package>

Aby usunąć zastąpienie:

adb shell am compat disable FORCE_RESIZE_APP <package>

Uwaga: te polecenia tylko tymczasowo stosują lub usuwają zastąpienie.

FORCE_NON_RESIZE_APP

Wymusza, aby pakiety, do których zastąpienie jest stosowane, nie były skalowalne i w przypadku zmian konfiguracji przechodziły w tryb zgodności z rozmiarem.

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

W manifeście aplikacji ustaw atrybut android:resizeableActivity i flagę metadanych android.supports_size_changes na false. Następnie określ orientację lub współczynnik kształtu.

Optymalizacja aplikacji

Wszystkie aplikacje, które zachowują się prawidłowo po zmianie rozmiaru, powinny mieć ustawioną wartość android:resizeableActivity lub android.supports_size_changes na true. Inne aplikacje powinny być ulepszone, aby dobrze działały po zmianie rozmiaru. Zobacz android:resizeableActivity.

Jak wyłączyć lub wyłączyć zastąpienie

Ustaw flagę właściwości PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES na false.

Flagi usług, które można dostosować do zastępowania

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

Polecenia adb do testowania zastąpienia

Aby zastosować zastąpienie i uniemożliwić zmianę rozmiaru aplikacji:

adb shell am compat enable FORCE_NON_RESIZE_APP <package>

Aby usunąć zastąpienie:

adb shell am compat disable FORCE_NON_RESIZE_APP <package>

Uwaga: te polecenia tylko tymczasowo stosują lub usuwają zastąpienie.

OVERRIDE_MIN_ASPECT_RATIO

Bramka dla wszystkich zastąpień, które narzucają określony minimalny format obrazu.

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Ustaw wartość android:minAspectRatio na poziomie aktywności lub aplikacji.

Optymalizacja aplikacji

Nie ustawiaj w aplikacji ograniczeń dotyczących formatu obrazu. Upewnij się, że aplikacja obsługuje różne rozmiary wyświetlacza. Używaj klas rozmiaru okna, aby obsługiwać różne układy w zależności od ilości miejsca na ekranie, jaką ma Twoja aplikacja. Zapoznaj się z interfejsami Compose WindowSizeClass API i View WindowSizeClass API.

Jak wyłączyć lub zrezygnować z zastąpienia

Określ ograniczenie formatu obrazu lub ustaw flagę właściwości PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE na false.

Flagi usługi do dostosowania zastępowania

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE"
  android:value="false"/>

Polecenia adb do testowania zastąpienia

Aby zastosować zastąpienie:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO <package>

Aby usunąć zastąpienie:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO <package>

Uwaga: te polecenia tylko tymczasowo stosują lub usuwają zastąpienie.

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

Ogranicza ustawienia aplikacji, które narzucają określony minimalny format obrazu w przypadku aktywności w orientacji pionowej. Domyślnie jest ona włączona i obowiązuje tylko wtedy, gdy włączona jest też zasada OVERRIDE_MIN_ASPECT_RATIO.

Polecenia adb do testowania zastąpienia

Aby zastosować zastąpienie:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Aby usunąć zastąpienie:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Uwaga: polecenia te tylko tymczasowo stosują lub usuwają zastąpienie.

OVERRIDE_MIN_ASPECT_RATIO_MEDIUM

Ustawia minimalny format obrazu aktywności na średni (3:2).

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Optymalizacja aplikacji

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Jak wyłączyć lub zrezygnować z zastąpienia

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Flagi usługi do dostosowania zastępowania

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Polecenia adb do testowania zastąpienia

Aby zastosować zastąpienie:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Aby usunąć zastąpienie:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Uwaga: te polecenia tylko tymczasowo stosują lub usuwają zastąpienie.

OVERRIDE_MIN_ASPECT_RATIO_LARGE

Ustaw minimalny format obrazu aktywności na dużą wartość (16:9).

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Optymalizacja aplikacji

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Jak wyłączyć lub zrezygnować z zastąpienia

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Flagi usługi do dostosowania zastępowania

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Polecenia adb do testowania zastąpienia

Aby zastosować zastąpienie:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>

Aby usunąć zastąpienie:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>`

Uwaga: te polecenia tylko tymczasowo stosują lub usuwają zastąpienie.

OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN

Umożliwia użycie proporcji podzielonego ekranu. Pozwala aplikacji na wykorzystanie całej dostępnej przestrzeni w trybie podzielonego ekranu, aby uniknąć letterboxingu.

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Optymalizacja aplikacji

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Jak wyłączyć lub zrezygnować z zastąpienia

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Flagi usługi do dostosowania zastępowania

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Polecenia adb do testowania zastąpienia

Aby zastosować zastąpienie:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Aby usunąć zastąpienie:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Uwaga: te polecenia tylko tymczasowo stosują lub usuwają zastąpienie.

OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN

Wyłącza minimalne zastąpienie formatu obrazu w trybie pionowym na pełnym ekranie, aby wykorzystać całą dostępną przestrzeń ekranu.

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Optymalizacja aplikacji

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Jak wyłączyć lub zrezygnować z zastąpienia

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Flagi usługi do dostosowania zastępowania

Zobacz OVERRIDE_MIN_ASPECT_RATIO.

Polecenia adb do testowania zastąpienia

Aby zastosować zastąpienie:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Aby usunąć zastąpienie:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Uwaga: te polecenia tylko tymczasowo stosują lub usuwają zastąpienie.

OVERRIDE_ANY_ORIENTATION

Umożliwia zastąpienie dowolnej orientacji za pomocą tych ustawień zastąpienia:

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Ustaw atrybut pliku manifestu activity:screenOrientation lub użyj interfejsu API Activity#setRequestedOrientation().

Optymalizacja aplikacji

Aplikacja powinna obsługiwać wszystkie orientacje. Zmiana orientacji to zmiana konfiguracji, którą można obsłużyć na 2 sposoby: pozwalając systemowi na zniszczenie i ponowne utworzenie aplikacji lub samodzielne zarządzanie zmianami konfiguracji. Jeśli zmiany konfiguracji wprowadzasz samodzielnie, stan aplikacji możesz zachować, używając ViewModel. W niewielu przypadkach możesz zdecydować się na zablokowanie orientacji tylko na małych ekranach, ale może to nie działać tak dobrze jak w przypadku umożliwienia użytkownikowi obracania aplikacji w razie potrzeby. W Androidzie 12L i nowszych wersjach orientacja może zostać zastąpiona przez konfigurację urządzenia. Więcej informacji o obsługiwaniu zmian konfiguracji i obsługiwaniu wszystkich orientacji znajdziesz w artykułach Obsługa zmian konfiguracji, Omówienie ViewModel i Ograniczenie orientacji aplikacji na telefonach, ale nie na urządzeniach z dużym ekranem.

Jak wyłączyć lub zrezygnować z zastąpienia

Ustaw flagę właściwości PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE na false.

Flagi usługi do dostosowania zastępowania

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE"
  android:value="true|false"/>

Polecenia adb do testowania zastąpienia

Aby zastosować zastąpienie:

adb shell am compat enable OVERRIDE_ANY_ORIENTATION <package>

Aby usunąć zastąpienie:

adb shell am compat disable OVERRIDE_ANY_ORIENTATION <package>

Uwaga: te polecenia tylko tymczasowo stosują lub usuwają zastąpienie.

OVERRIDE_ANY_ORIENTATION_TO_USER

Umożliwia aplikacji wypełnienie dostępnej przestrzeni wyświetlacza. Zastępuje wszelkie ograniczenia dotyczące orientacji, możliwości zmiany rozmiaru i proporcji obrazu określone w pliku manifestu aplikacji. Ponadto ignoruje wszystkie połączenia z numerem Activity#setRequestedOrientation().

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Nie ustawiaj atrybutu pliku manifestu android:screenOrientation ani nie ustawiaj go na "user".
Ustaw atrybut pliku manifestu android:resizeableActivity na true.

Uwaga: ustawienia android:minAspectRatio i android:maxAspectRatio są ignorowane, jeśli ustawienie resizeableActivity ma wartość true.
Na małych ekranach, aby umożliwić zmianę rozmiaru aplikacji przy jednoczesnym wyłączeniu trybu wielookienkowego za pomocą flagi metadanych android:resizeableActivity=false, ustaw flagę metadanych android.supports_size_changes na true. Nie ustawiaj opcji minAspectRatio i maxAspectRatio.

Uwaga: w Androidzie 12 (poziom API 31) wszystkie aplikacje działają w trybie wielookiennym na dużych ekranach (średniej lub rozszerzonej klasy rozmiaru okna) niezależnie od konfiguracji aplikacji. Zobacz Obsługa trybu wielu okien
.

Optymalizacja aplikacji

Umożliw aplikacji obsługę wszystkich orientacji. Nie ustawiaj specyfikacji screenOrientation w manifeście aplikacji. Obsługuj aplikację w różnych rozmiarach, trybie wielookiennym i przy wszystkich proporcjach ekranu, ustawiając atrybut android:resizeableActivity w pliku manifestu aplikacji na true. Zapoznaj się z artykułem Obsługa różnych rozmiarów wyświetlania.

Tryb zgodności urządzenia

Urządzenia referencyjne

Typowe problemy ze zgodnością

Letterboxing

Problem

Aplikacja ograniczona do orientacji pionowej, nieużyteczna na urządzeniu w orientacji poziomej.

Optymalizacja

Aplikacja obsługuje wszystkie orientacje urządzenia.

Sposób obejścia problemu z kompatybilnością

Tryb zgodności rozmiaru

Problem

Aplikacja bez możliwości zmiany rozmiaru ulega awarii w trybie wielu okien.

Optymalizacja

Aplikacja działa we wszystkich rozmiarach okien.

Sposób obejścia problemu z kompatybilnością

Aplikacja w orientacji pionowej w ramce w orientacji poziomej, z przeskalowaniem za pomocą elementu sterującego ponownym uruchamianiem.

migające pętle,

Problem

Aplikacja przeznaczona tylko do wyświetlania w orientacji poziomej, gdy wyświetlacz jest w orientacji pionowej, wielokrotnie wywołuje Activity#setRequestedOrientation().

Optymalizacja

Aplikacja obsługuje zmianę konfiguracji, nie ma ograniczeń orientacji, więc nie wchodzi w pętlę migotania.

Sposób obejścia problemu z kompatybilnością

Podgląd z aparatu

Problem

Nieprawidłowo wyrównany i zniekształcony podgląd z aparatu na składanym urządzeniu z dużym ekranem

Optymalizacja

Podgląd aparatu jest prawidłowo wyrównany i powiększony we wszystkich orientacjach urządzenia.

Sposób obejścia problemu z kompatybilnością

Tablet – wymuszenie obracania aplikacji ograniczonej do orientacji pionowej.

składany – wymuszenie obracania aplikacji ograniczonej do orientacji pionowej. Aplikacja jest też wyświetlana w letterboxie.

Interfejsy API, których użytkownicy często nadużywają

Problem

Wycofany interfejs API błędnie oblicza granice aplikacji. Treści aplikacji znikają z ekranu.

Optymalizacja

Interfejs API poprawnie oblicza dane okna aplikacji.

Sposób obejścia problemu z kompatybilnością

przejrzyste działania

Problem

Dialog został nieprawidłowo umieszczony, ponieważ aktywność została uruchomiona z trampoliny.

Optymalizacja

Zaokrąglone narożniki

Okno z zaokrąglonymi rogami prawidłowo umieszczone nad widoczną aktywnością uruchamiania.

Sposób obejścia problemu z kompatybilnością

Gry w Unity

Problem

Gra traci fokus w trybie wielu okien i renderuje się jako czarne okno.

Optymalizacja

Gra prawidłowo renderuje treści w trybie wielu okien, nawet jeśli nie jest w centrum uwagi.

Sposób obejścia problemu z kompatybilnością

Testowanie aplikacji pod kątem problemów ze zgodnością

jest w formacie letterbox,

Kotlin

Java

Kotlin

Java

Zastąpienia na poziomie aplikacji

Zastępowanie użytkownika w poszczególnych aplikacjach

Zastąpienia producenta urządzenia według aplikacji

FORCE_RESIZE_APP

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Optymalizacja aplikacji

Jak wyłączyć lub zrezygnować z zastąpienia

Flagi usług, które można dostosować do zastępowania

Polecenia adb do testowania zastąpienia

FORCE_NON_RESIZE_APP

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Optymalizacja aplikacji

Jak wyłączyć lub wyłączyć zastąpienie

Flagi usług, które można dostosować do zastępowania

Polecenia adb do testowania zastąpienia

OVERRIDE_MIN_ASPECT_RATIO

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Optymalizacja aplikacji

Jak wyłączyć lub zrezygnować z zastąpienia

Flagi usługi do dostosowania zastępowania

Polecenia adb do testowania zastąpienia

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

Jak aplikacje mogą osiągnąć ten sam efekt co zastąpienie

Optymalizacja aplikacji

Jak wyłączyć lub zrezygnować z zastąpienia

Aplikacja przeznaczona tylko do wyświetlania w orientacji poziomej, gdy wyświetlacz jest w orientacji pionowej, wielokrotnie wywołuje `Activity#setRequestedOrientation()`.