Esta página foi traduzida pela API Cloud Translation.

Modo de compatibilidade do dispositivo

O Android ativa um modo de compatibilidade para apps que declaram restrições de orientação ou redimensionamento. O modo de compatibilidade garante um comportamento aceitável do app em dispositivos de tela grande e smartphones dobráveis, mas com usabilidade abaixo do ideal.

As substituições por app permitem que fabricantes de dispositivos, proprietários de dispositivos virtuais¹ e usuários mudem o comportamento do app para melhorar o layout ou evitar falhas em dispositivos específicos.

Android 16

O Android 16 (nível da API 36) ignora as restrições de orientação da tela, proporção e redimensionamento de apps para melhorar o layout deles em formatos com largura mínima >= 600 dp.

As seguintes substituições por app não funcionam para apps direcionados ao nível da API 36:

FORCE_RESIZE_APP
FORCE_NON_RESIZE_APP
OVERRIDE_MIN_ASPECT_RATIO
OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY
OVERRIDE_MIN_ASPECT_RATIO_MEDIUM
OVERRIDE_MIN_ASPECT_RATIO_LARGE
OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN
OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN
OVERRIDE_ANY_ORIENTATION
OVERRIDE_ANY_ORIENTATION_TO_USER
OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE
OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA
OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION
OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION
OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED
OVERRIDE_RESPECT_REQUESTED_ORIENTATION
OVERRIDE_EXCLUDE_CAPTION_INSETS_FROM_APP_BOUNDS

Desativar

O app pode segmentar o nível 36 da API, mas recusar o comportamento do Android 16. Nesse caso, OVERRIDE_ANY_ORIENTATION_TO_USER não se aplica.

Aviso:

Todas as substituições, exceto OVERRIDE_ANY_ORIENTATION_TO_USER, são aplicáveis mesmo que o app desative o comportamento do Android 16. Portanto, a orientação da tela, a proporção e as restrições de redimensionamento do app ainda podem ser substituídas se os fabricantes de dispositivos tiverem implementado as substituições.
Os usuários podem substituir a proporção da tela do app em Configurações, mesmo que o app desative essa opção. Consulte Substituições por app do usuário.
Modo Janela para computador:
- As restrições de orientação são substituídas, mesmo que o app tenha recusado.
- As restrições de redimensionamento são respeitadas se o app desativar essa opção. No entanto, é possível aplicar o redimensionamento dimensionado.

Declarar propriedade do manifesto

Para desativar o comportamento do nível 36 da API, declare a propriedade de manifesto PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY.

Para desativar uma atividade específica, defina a propriedade no elemento <activity>:

<activity ...>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"
        android:value="true" />
    ...
</activity>

Para desativar o recurso em todo o app, defina a propriedade no elemento <application>:

<application ...>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"
        android:value="true" />
    ...
</application>

Dispositivos de referência

Os seguintes dispositivos podem exigir substituições por app devido a configurações incomuns ou que não são bem compatíveis com apps:

Tablets:a orientação natural de alguns tablets, como o Pixel Tablet, é paisagem. Um dispositivo está na orientação natural quando Display#getRotation() retorna Surface.ROTATION_0. Se os apps presumirem que ROTATION_0 está no modo retrato, os layouts dos apps e a visualização da câmera poderão não corresponder à tela do dispositivo.
Dispositivos dobráveis na horizontal:alguns dispositivos dobráveis, como o Pixel Fold, ficam na orientação retrato quando dobrados, mas na orientação paisagem quando desdobrados. Se os apps presumirem que a orientação desdobrada é retrato, é provável que ocorram loops de tremulação ou problemas de layout.
Smartphones dobráveis:os smartphones dobráveis abertos geralmente estão na orientação retrato. No entanto, quando dobrados, os smartphones geralmente têm uma pequena tela na orientação horizontal. Os apps precisam identificar e se adaptar às diferentes orientações das telas.
Telas externas:alguns dispositivos podem iniciar uma sessão de janelas da área de trabalho em telas externas conectadas. Os apps precisam consultar telas externas para informações como tamanho e resolução da tela. Caso contrário, eles podem fazer suposições incorretas sobre as telas, o que pode levar a um comportamento incorreto do app.
Telas de carro:muitas, mas não todas, são horizontais. O desenvolvimento de apps estacionados para telas de carro é semelhante ao desenvolvimento para tablets.

Problemas comuns de compatibilidade

Os apps apresentam problemas de compatibilidade com mais frequência devido a restrições de orientação, redimensionamento e proporção, processamento incorreto da orientação de visualização da câmera e uso indevido de APIs.

Letterboxing

O efeito letterbox posiciona o app no centro da tela ou, em telas grandes, em um dos lados para facilitar o acesso. Efeitos foscos (barras de cor sólida ou plano de fundo desfocado) preenchem a área de exibição não usada nas laterais ou nas partes de cima e de baixo do app.

O efeito letterbox costuma ser usado em dispositivos de tela grande porque as dimensões e a proporção da tela deles geralmente são diferentes daquelas dos smartphones padrão, para os quais a maioria dos apps foi criada.

Figura 1. Um app restrito à orientação de retrato tem efeito letterbox no tablet em modo paisagem e no dispositivo dobrável.

Problema

O app não oferece suporte a todas as configurações de tela porque tem orientação e proporção fixas ou não é redimensionável.

As configurações que controlam a orientação e a capacidade de redimensionamento do app incluem:

screenOrientation: especifica uma orientação fixa para um app. Os apps também podem definir a orientação durante a execução usando Activity#setRequestedOrientation().
resizeableActivity: indica se o sistema pode redimensionar apps para que se ajustem a janelas de dimensões variadas. No Android 11 (nível 30 da API) e versões anteriores, especifica se os apps oferecem suporte ao modo de várias janelas. No Android 12 (nível 31 da API) e versões mais recentes, especifica se os apps oferecem suporte ao modo de várias janelas em telas pequenas (classe de tamanho de janela compacta). No Android 12 e versões mais recentes, os apps oferecem suporte ao modo de várias janelas em telas grandes (classe de tamanho de janela média ou expandida), independente dessa configuração.
maxAspectRatio: especifica a proporção máxima a que o app oferece suporte. Somente os apps com a resizeableActivity definida como false podem definir a maxAspectRatio.
minAspectRatio: especifica a proporção mínima compatível com o app. Somente apps com resizeableActivity definido como false podem definir minAspectRatio.

Um app restrito à orientação retrato não pode ser usado em um dispositivo em modo paisagem.

Otimização

O app precisa oferecer suporte a todos os tamanhos e orientações de exibição no modo de várias janelas de todos os dispositivos. Remova todas as restrições de orientação e proporção fixa dos layouts e do arquivo de manifesto do app.

O app oferece suporte a todas as orientações de dispositivo.

Solução alternativa para compatibilidade

Se um app com orientação ou proporção fixa for aberto em uma janela que não ofereça suporte diretamente ao tamanho ou à orientação da janela, o Android aplicará o efeito letterbox para preservar a continuidade.

No Android 12 (nível 31 da API) e 12L (nível 32 da API), a plataforma aplica várias melhorias a apps com efeito letterbox. Os fabricantes de dispositivos implementam as melhorias na interface. Você não precisa fazer nenhum desenvolvimento adicional para que seu app se beneficie das melhorias.

O Android 12 (nível 31 da API) lançou as melhorias estéticas abaixo, que podem ser configuradas pelos fabricantes de dispositivos:

Cantos arredondados: os cantos da janela do app têm uma aparência mais refinada.
Transparência da barra de sistema:as barras de status e navegação, que se sobrepõem ao app, são semitransparentes, o que deixa os ícones das barras sempre visíveis sobre o plano de fundo com efeito letterbox.
Proporção configurável:a proporção do app pode ser ajustada para melhorar a aparência dele.

Figura 2. App com efeito letterbox com melhorias na interface.

O 12L (nível 32 da API) adicionou estas melhorias funcionais:

Posicionamento configurável:em telas grandes, os fabricantes de dispositivos podem posicionar o app no lado esquerdo ou direito da tela, facilitando a interação.
Botão de reinicialização reformulado:os fabricantes de dispositivos podem oferecer uma nova aparência ao botão de reinicialização no modo de compatibilidade de tamanho para que os usuários possam o reconhecer com mais facilidade.

O Android 13 (nível 33 da API) adicionou uma caixa de diálogo com instruções para o usuário sobre como posicionar o app com efeito letterbox na tela ou como incluir esse efeito no modo de tela dividida:

Figura 3. App com efeito letterbox mostrando a caixa de diálogo com instruções para o usuário.

Modo de compatibilidade de tamanho

O modo de compatibilidade de tamanho é o efeito letterbox que mantém a proporção do app e inclui um controle de reinicialização. O controle permite que os usuários reiniciem o app e mostrem de novo o conteúdo da tela. O Android invoca o modo de compatibilidade de tamanho para apps que não são redimensionáveis. Quando uma atividade é movida para um contêiner de exibição incompatível com as dimensões da atividade, o sistema pode redimensionar o app para preencher a tela do dispositivo em pelo menos uma dimensão.

As mudanças na configuração do dispositivo que podem acionar o modo de compatibilidade de tamanho incluem:

Rotação do dispositivo
Dobrar ou desdobrar dispositivos dobráveis
Alternar entre os modos de exibição de tela cheia e tela dividida

Problema

O modo de compatibilidade de tamanho normalmente se aplica a atividades com orientação ou proporção restritas e que são configuradas (ou determinadas pelo sistema) para não serem redimensionáveis.

Seu app será considerado redimensionável e não será colocado no modo de compatibilidade de tamanho se atender a um destes critérios:

Pode ser redimensionado com resizeableActivity="true".
Oferece suporte ao modo picture-in-picture.
É incorporado.
A substituição por app FORCE_RESIZE_APP foi aplicada pelo fabricante do dispositivo (as propriedades definidas pelo app são ignoradas).

Se o app não atender a nenhuma das condições, ele não será considerado redimensionável e poderá ser colocado no modo de compatibilidade de tamanho.

Um app não redimensionável falha no modo de várias janelas.

Otimização

O app precisa oferecer suporte a todos os tamanhos de tela. Para tornar seu app redimensionável, defina o atributo android:resizeableActivity do elemento <activity> ou <application> como true no manifesto do app. Crie layouts responsivos/adaptáveis para o app. Para mais informações, consulte Suporte a diferentes tamanhos de tela e Suporte ao modo de várias janelas.

O app funciona em todos os tamanhos de janela.

Solução alternativa para compatibilidade

O Android coloca um app no modo de compatibilidade de tamanho quando o sistema determina que a exibição do app com efeito letterbox pode ser melhor se o app for redimensionado para preencher a janela de exibição em pelo menos uma dimensão. O sistema mostra um controle de reinicialização que recria o processo do app, refazendo a atividade e redesenhando a tela. Consulte também Visão geral dos processos e threads.

Um app restrito à orientação de retrato é mostrado com efeito letterbox na orientação paisagem, redimensionado pelo controle de reinicialização.

Modo de compatibilidade de exibição

O modo de compatibilidade de exibição impede que um app seja reiniciado quando ele se move entre diferentes telas, o que pode acionar uma mudança de configuração, como um modo de cor, disponibilidade de tela sensível ao toque ou mudança de densidade da tela.

O modo de compatibilidade de exibição é ativado por padrão para jogos (com base na flag android:appCategory) para melhorar a estabilidade e a continuidade. Ao contrário do modo de compatibilidade de tamanho, o modo de compatibilidade de tela não congela a configuração do app. O app ainda pode receber todas as atualizações de configuração por APIs, como o callback onConfigurationChanged(), mas não precisa passar por uma reinicialização disruptiva. Isso significa que os jogos que oferecem suporte adequado a APIs como onConfigurationChanged() ainda podem atualizar a interface de maneira responsiva, mesmo que estejam no modo de compatibilidade de exibição.

Para desativar o modo de compatibilidade de exibição e processar mudanças de configuração no app, declare suporte para as mudanças de configuração no arquivo AndroidManifest.xml do app e processe as mudanças de configuração no callback onConfigurationChanged().

<activity
    android:name=".MyGameActivity"
    android:configChanges="colorMode|touchscreen|density|...">
    ...
</activity>

Repetições intermitentes

Quando um app não oferece suporte a todas as orientações da tela, ele pode solicitar de forma repetida novas orientações após a mudança de configuração, criando uma repetição infinita que faz a tela piscar ou o app girar indefinidamente.

Problema

No Android 12 (nível 31 da API) e versões mais recentes, os fabricantes de dispositivos podem configurar os dispositivos para ignorar restrições de orientação especificadas pelos apps e, em vez disso, aplicar modos de compatibilidade. Por exemplo, um dispositivo dobrável pode ignorar a configuração android:screenOrientation="portrait" de uma atividade quando ela for mostrada na tela interna com tamanho de tablet no modo paisagem.

Se as restrições de orientação de um app forem ignoradas, ele poderá definir de forma programática a orientação chamando Activity#setRequestedOrientation(). A chamada aciona uma reinicialização do app se ele não estiver processando as mudanças de configuração. Consulte Processar mudanças de configuração. Após a reinicialização, as restrições de orientação do app serão ignoradas de novo, o app repetirá a chamada para setRequestedOrientation(), a chamada acionará uma reinicialização do app e assim por diante, em uma repetição contínua.

Você também pode encontrar essa situação quando a orientação natural (a orientação normal determinada pelo Android) de uma tela de dispositivo for de paisagem. Isso é, chamar Display#getRotation() retorna Surface.ROTATION_0 enquanto o dispositivo está com uma proporção de paisagem. Historicamente, os apps presumem que Display.getRotation() = Surface.ROTATION_0 significa que o dispositivo está na orientação retrato. Mas isso nem sempre acontece (por exemplo, na tela interna de alguns dispositivos dobráveis e em alguns tablets).

Um app na orientação paisagem em uma tela interna dobrável pode verificar a rotação da tela, receber um valor de ROTATION_0, presumir que a orientação natural do dispositivo é retrato e chamar setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT ) para reconfigurar o layout do app. Depois que o app for reiniciado (na orientação paisagem), ele poderá conferir de novo a rotação da tela, receber um valor de ROTATION_0, chamar setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT) e continuar a repetição infinita.

Um app somente paisagem no modo retrato faz chamadas repetidas para `Activity#setRequestedOrientation()`.

Otimização

Os apps não podem:

Definir uma orientação padrão com Activity#setRequestedOrientation() no método de atividade onCreate(), porque a solicitação de orientação pode ser acionada inesperadamente por mudanças de configuração não processadas.
Presumir que a orientação natural do dispositivo (ROTATION_0) seja retrato.
Definir a orientação com base em sinais não relacionados ao tamanho da janela atual, como Display#getRotation(), a presença de um FoldingFeature ou de APIs descontinuadas.

O app processa mudanças de configuração e não tem restrições de orientação, dessa forma, não entra em uma repetição intermitente.

Solução alternativa para compatibilidade

O Android ignora chamadas para Activity#setRequestedOrientation() nestas situações:

A atividade já foi reiniciada em uma chamada anterior para o método ou o tratamento de rotação forçada de compatibilidade da câmera foi ativado (consulte Visualização da câmera abaixo).

Os fabricantes de dispositivos podem aplicar esse comportamento a um app com OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION.
A atividade fez mais de duas solicitações de orientação em um segundo, o que indica que houve uma repetição. Das duas solicitações na repetição, o Android usa a que maximiza a área de exibição do app.

Os fabricantes de dispositivos podem aplicar esse comportamento a um app com OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED.
Os proprietários de dispositivos virtuais substituíram a chamada de método em alguns dispositivos.

Visualização da câmera

A visualização da câmera (ou o visor) dos apps de câmera pode ficar desalinhada ou distorcida em telas de tablets, laptops e dispositivos dobráveis.

Problema

O Documento de definição de compatibilidade do Android declara que um sensor de imagem de câmera "PRECISA estar orientado de forma que a dimensão longa da câmera se alinhe à dimensão longa da tela".

Os apps geralmente presumem que a orientação do dispositivo e do sensor da câmera são retrato, uma suposição razoável nos smartphones padrão. Mas a orientação natural dos tablets, laptops e sensores da câmera pode ser paisagem. Além disso, novos formatos, como dobráveis, podem ter várias orientações naturais e diversos sensores de câmera em diferentes orientações.

Iniciar uma atividade com uma orientação de câmera não esperada pelo app ou alternar entre diferentes câmeras ou telas de dispositivos (no caso de dobráveis) pode fazer com que a visualização da câmera fique desalinhada ou distorcida.

Visualização da câmera desalinhada e distorcida em uma tela grande dobrável.

Otimização

Os apps de câmera precisam identificar e gerenciar corretamente a orientação do dispositivo e do sensor da câmera para mostrar uma visualização da câmera alinhada e dimensionada corretamente. Os apps precisam calcular a rotação do dispositivo e do sensor e a proporção da tela ou da janela e, em seguida, aplicar os resultados à visualização da câmera. Para orientações detalhadas, consulte Visualização da câmera e Apresentação do visor da câmera.

Visualização da câmera alinhada e dimensionada corretamente em todas as orientações do dispositivo.

Solução alternativa para compatibilidade

Um dispositivo está na orientação natural quando Display#getRotation() retorna Surface.ROTATION_0. O sistema calcula CameraCharacteristics.SENSOR_ORIENTATION usando a orientação natural do dispositivo. O Android alinha a janela em retrato com a orientação natural do dispositivo para apps restritos ao modo retrato, que é o que a maioria dos apps espera. O Android também corta a imagem do sensor da câmera quando a orientação do sensor é paisagem e a visualização da câmera é retrato. As alternativas específicas incluem:

Forçar a rotação da visualização da câmera em apps restritos a retrato:os apps restritos à orientação retrato esperam que a orientação natural do dispositivo e a orientação do sensor da câmera sejam retrato. No entanto, no Android 12 (nível 31 da API) e versões mais recentes, os apps podem ser executados em várias orientações do dispositivo se os fabricantes ignorarem a especificação de orientação.

Quando um app restrito ao modo retrato estiver conectado à câmera, o Android forçará a rotação do app para alinhar a janela na orientação retrato com a orientação natural do dispositivo.

Em alguns tablets (consulte os dispositivos de referência), a janela em retrato do app é girada para o modo retrato em tela cheia para se alinhar à orientação natural do dispositivo. O app ocupa a tela inteira após a rotação forçada.

Tablet: rotação forçada do app restrito a modo retrato.

Na tela interna no modo paisagem de dispositivos dobráveis (consulte dispositivos de referência), as atividades somente no modo retrato são giradas para o modo paisagem para ficarem alinhadas à orientação natural desdobrada. O app recebe o efeito letterbox após a rotação forçada.

Dispositivo dobrável: rotação forçada do app restrito ao modo retrato. O app também tem efeito letterbox.

Observação: a rotação forçada não acontece se o app for responsivo e processar as orientações retrato e paisagem.
Recorte da câmera frontal interna:o sensor da câmera frontal interna de alguns dispositivos dobráveis está na orientação paisagem. Além de forçar a rotação da visualização da câmera na tela interna dobrável, o Android corta o campo de visão da parte frontal interna (em modo paisagem) para que o sensor capture uma visão oposta à orientação do dispositivo.
Forçar a atualização da visualização da câmera:o sistema alterna entre os métodos de atividade onStop() e onStart() (por padrão) ou onPause() e onResume() (aplicado por OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE por substituição de app) após a rotação forçada para garantir que a visualização da câmera seja mostrada corretamente.
Dimensionamento da proporção:o sistema muda dinamicamente a proporção da visualização forçada da câmera para que ela tenha uma proporção mínima mais alta, o que garante que a visualização da câmera seja dimensionada corretamente.

Os desenvolvedores de apps poderão substituir essas soluções alternativas se os apps processarem a visualização da câmera corretamente. Consulte Substituições por app.

APIs usadas indevidamente com frequência

Como o Android adicionou suporte a recursos como o modo de várias janelas e dispositivos como os dobráveis, as APIs legadas foram descontinuadas e substituídas por APIs atualizadas, que funcionam em todos os tamanhos de tela e formatos de dispositivos. No entanto, as APIs descontinuadas ainda estão disponíveis para compatibilidade com versões anteriores.

Algumas APIs View são desenvolvidas para fins especiais que nem sempre são bem compreendidos pelos desenvolvedores.

Problema

Os desenvolvedores continuam usando as APIs Display descontinuadas e presumem incorretamente que elas retornam os limites do app, em vez dos limites da área de exibição do dispositivo. Ou os desenvolvedores usam APIs View com fins especiais por engano para receber métricas gerais de exibição. O resultado são erros de cálculo ao reposicionar elementos da interface após eventos de redimensionamento da janela do app, o que causa problemas de layout.

APIs Display descontinuadas e usadas indevidamente com frequência:

Para mais informações, consulte Suporte ao modo de várias janelas.

APIs View usadas indevidamente:

Uma API descontinuada calcula de forma incorreta os limites do app. O conteúdo do app sai da tela.

Otimização

Nunca confie no tamanho de exibição físico ao posicionar elementos da interface. Migre seu app para APIs baseadas em WindowMetrics, incluindo estas APIs WindowManager:

Plataforma:
- getCurrentWindowMetrics()
- getMaximumWindowMetrics()
Jetpack:
- WindowMetricsCalculator#computeCurrentWindowMetrics()
- WindowMetricsCalculator#computeMaximumWindowMetrics()

A API calcula corretamente as métricas da janela do app.

Solução alternativa para compatibilidade

Duas substituições ajustam as APIs Display descontinuadas e as APIs View usadas indevidamente para retornar os limites do app: ALWAYS_SANDBOX_DISPLAY_APIS para APIs Display e OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS para APIs View. ALWAYS_SANDBOX_DISPLAY_APIS também é aplicada por padrão a apps qualificados para o modo de compatibilidade de tamanho.

Atividades transparentes

As atividades transparentes são resultado de estilos de segundo plano transparentes como:

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

Temas relacionados a caixas de diálogo, como Theme.MaterialComponents.Dialog, podem incluir estilos que tornam as atividades transparentes.

As atividades transparentes não cobrem todo o espaço de exibição disponível, o que dificulta o gerenciamento delas, porque a área de exibição disponível pode mudar com base em mudanças de configuração, como o modo de várias janelas do dispositivo ou o aparelho dobrando, desdobrando ou rotacionando.

Problema

Uma atividade transparente precisa se adequar aos limites da primeira atividade opaca abaixo dela na pilha de atividades da tarefa. No entanto, uma atividade opaca que abre uma caixa de diálogo de permissão pode ser um trampolim (uma atividade que inicia outra e desaparece). Assim, o sistema não pode determinar os limites da atividade trampolim que iniciou a atividade de caixa de diálogo de permissão transparente.

A caixa de diálogo foi posicionada incorretamente porque a atividade foi iniciada em um trampolim.

Otimização

Atividades transparentes herdam as restrições da atividade opaca mais acima na pilha de atividades de uma tarefa. A atividade opaca precisa estar disponível durante todo o ciclo de vida da atividade transparente, desde a criação até a destruição. Por isso, não inicie solicitações de permissão usando atividades trampolim.

Se uma atividade trampolim iniciar uma solicitação de permissão, a caixa de diálogo de permissão talvez não apareça, porque essa atividade será destruída antes do usuário conseguir responder à caixa de diálogo, e as dimensões e a posição da atividade de caixa de diálogo podem ter sido calculadas incorretamente.

Os apps precisam sempre iniciar solicitações de permissão em atividades que permanecem visíveis até que o usuário decida sobre a permissão.

Bordas arredondadas

Uma atividade pode ser transparente devido a um estilo que especifica a transparência do plano de fundo ou porque o conteúdo da atividade não preenche o espaço de exibição disponível. Se uma atividade transparente preencher o espaço de exibição disponível, o sistema aplicará automaticamente cantos arredondados a ela se isso tiver sido configurado pelo fabricante do dispositivo. No entanto, se uma atividade transparente (como uma caixa de diálogo de permissão) não preencher o espaço disponível, caberá a você decidir se quer ou não aplicar cantos arredondados.

As caixas de diálogo de permissão não preenchem o espaço de exibição disponível porque o layout delas normalmente usa LayoutParams.WRAP_CONTENT, em vez de LayoutParams.MATCH_PARENT.

Caixa de diálogo com cantos arredondados posicionada corretamente sobre a atividade de inicialização visível.

Solução alternativa para compatibilidade

Mantenha as atividades que iniciam atividades da caixa de diálogo visíveis até o usuário interagir com a caixa.

O sistema garante que uma atividade transparente herde todas as restrições da primeira atividade opaca abaixo da atividade transparente na pilha de atividades, incluindo restrições relacionadas a:

Modo de compatibilidade de tamanho
Orientação
Proporção

Jogos do Unity

Os jogos do Unity são executados no modo de tela cheia ou de várias janelas do Android. No entanto, muitos jogos do Unity perdem o foco e param de mostrar conteúdo quando o app é colocado no modo de várias janelas.

Problema

O Unity adicionou uma opção Resizable Window (link em inglês) na versão 2019.4 para oferecer suporte ao modo de várias janelas no Android. No entanto, a implementação inicial não reagia corretamente ao ciclo de vida da atividade no modo de várias janelas. Isso fazia com que o UnityPlayer suspendesse a reprodução quando o app perdia o foco. O jogador renderizava uma tela preta ou o último frame congelado do jogo. A jogabilidade era retomada apenas quando o usuário tocava na tela. Muitos apps que usam o mecanismo do Unity enfrentam esse problema e são renderizados como uma janela preta no modo de várias janelas.

O jogo perde o foco no modo de várias janelas e é renderizado como uma janela preta.

Otimização

Faça upgrade do Unity para a versão 2019.4.40 ou mais recente e exporte seu jogo de novo. Mantenha a opção Resizable Window marcada nas configurações do player do Android. Caso contrário, o jogo será pausado quando não estiver em foco, mesmo que esteja totalmente visível no modo de várias janelas.

O jogo renderiza conteúdo corretamente no modo de várias janelas, mesmo quando não está em foco.

Solução alternativa para compatibilidade

Os fabricantes de dispositivos podem aplicar a substituição OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS por app para fornecer um evento de foco falso a um app no modo de várias janelas. A substituição permite que a atividade mostre de novo o conteúdo e não seja ocultada.

Modo janela para computador

Quando os apps são executados em um ambiente de janelas de computador, eles podem encontrar modos de compatibilidade adicionais.

Os apps com orientação bloqueada podem ser redimensionados livremente. Mesmo que uma atividade esteja bloqueada para a orientação retrato, os usuários ainda podem redimensionar o app para a orientação paisagem.

Animação de um app no modo retrato sendo redimensionado para o modo paisagem.

Os apps com orientação bloqueada ainda podem ser redimensionados livremente.

No entanto, se uma atividade for declarada como não redimensionável (resizeableActivity = false), a interface da atividade será dimensionada mantendo a mesma proporção.

Animação do app sendo redimensionado. A interface é dimensionada para preencher a janela da área de trabalho.

As atividades declaradas como não redimensionáveis têm a interface dimensionada.

Prévia da câmera em janelas de computador

Quando os apps em janelas de computador iniciam uma visualização da câmera, a interface do visor é dimensionada, mantendo a proporção original. O restante da janela do app pode ser redimensionado livremente.

Redimensionar uma janela com um visor de câmera

Testar um app para verificar problemas de compatibilidade

Para testar seu app e entender como ele se comporta em diferentes formatos, use estes recursos:

Streaming de dispositivos:para testar o app em dispositivos de produção (incluindo dispositivos de referência) hospedados nos data centers do Google, consulte Streaming de dispositivos Android com tecnologia do Firebase .
Emuladores no Android Studio:para informações sobre como criar emuladores para dispositivos de referência, consulte Criar e gerenciar dispositivos virtuais
Emulador redimensionável do Android Studio:para informações sobre como acessar dispositivos virtuais, consulte Executar apps no Android Emulator.

Efeito letterbox

Verifique se cada atividade pode usar todo o espaço de exibição disponível para o app. Primeiro, declare o código a seguir na pasta de teste:

Kotlin

fun isLetterboxed(activity: AppCompatActivity): 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()
    }
}DeviceCompatibilityModeKotlinSnippets.kt

Java

public boolean isLetterboxed(AppCompatActivity 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();
}DeviceCompatibilityModeJavaSnippets.java

Em seguida, execute um teste para declarar o comportamento e garantir que a atividade de destino não tenha efeito letterbox:

Kotlin

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

@Test
fun activity_launched_notLetterBoxed() {
    activityRule.scenario.onActivity {
        assertFalse(it.isLetterboxed())
    }
}DeviceCompatibilityModeTestKotlinSnippets.kt

Java

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

@Test
public void activity_launched_notLetterBoxed() {
    try (ActivityScenario<MainActivity> scenario =
        ActivityScenario.launch(MainActivity.class)) {
            scenario.onActivity( activity -> {
                assertFalse(activity.isLetterboxed());
            });
        }
}DeviceCompatibilityModeTestJavaSnippets.java

O ideal é executar esse tipo de teste apenas até que ele seja aprovado e declare que as atividades do app ocupam todo o espaço de exibição disponível. Teste seu app em todos os tipos de dispositivo para garantir um comportamento consistente.

Substituições por app

O Android oferece substituições que mudam o comportamento configurado dos apps. Por exemplo, a substituição FORCE_RESIZE_APP instrui o sistema a ignorar o modo de compatibilidade de tamanho e redimensionar o app para se ajustar às dimensões de exibição, mesmo que resizeableActivity="false" esteja especificado no manifesto do app.

Os fabricantes de dispositivos aplicam substituições a apps selecionados ou a todos os apps em dispositivos de tela grande específicos. No Android 14 (nível 34 da API) e versões mais recentes, os usuários podem aplicar substituições aos apps nas configurações do dispositivo. No Android 16 (nível 36 da API) e versões mais recentes, os proprietários de dispositivos virtuais aplicam substituições em dispositivos selecionados que eles gerenciam.

Substituições por app do usuário

No Android 14 e em versões mais recentes, um menu de configurações permite que os usuários mudem a proporção dos apps. Dispositivos de tela grande, como os dispositivos de referência, implementam o menu.

O menu contém uma lista de todos os apps instalados no dispositivo. Os usuários escolhem um app e definem a proporção da tela como 3:4, 1:1, tela cheia ou outro valor configurado pelo fabricante do dispositivo. Os usuários também podem redefinir a proporção para o padrão do app, que é especificado no manifesto do app.

Os apps podem recusar a substituição de compatibilidade definindo as seguintes tags PackageManager.Property:

PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE

Para recusar a substituição de compatibilidade de proporção da tela do usuário, adicione a propriedade ao manifesto do app e defina o valor como false:
```
<application>
    <property
        android:name="android.window.
        PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE"
        android:value="false" />
</application>
```
Seu app será excluído da lista de apps nas configurações do dispositivo. Os usuários não poderão substituir a proporção do app.

Definir a propriedade como true não tem efeito.
PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE

Para desativar a opção de tela cheia da substituição de compatibilidade de proporção da tela do usuário, adicione a propriedade ao manifesto do app e defina o valor como false:
```
<application>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE"
        android:value="false" />
</application>
```
A opção de tela cheia é removida da lista de opções de proporção na configuração do dispositivo. Os usuários não poderão aplicar a substituição em tela cheia ao seu app.

Cuidado: se PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE for false, essa propriedade não terá efeito.

Definir essa propriedade como true não tem efeito.

Otimize seu app para todas as telas:não defina restrições de proporção no app. Use classes de tamanho de janela para oferecer suporte a diferentes layouts com base no espaço de exibição disponível.

Substituições por app no dispositivo

Os fabricantes de dispositivos e proprietários de dispositivos virtuais (selecione apps confiáveis e privilegiados) aplicam substituições por app em dispositivos específicos, incluindo tablets, dobráveis, dispositivos ChromeOS e telas de carro. Os dispositivos de referência podem aplicar algumas das substituições a uma variedade de apps por padrão.

Os apps podem recusar a maioria das substituições. Consulte a tabela Substituições por app abaixo.

Você pode testar seu app com as substituições ativadas ou desativadas usando o framework de compatibilidade (consulte Ferramentas do framework de compatibilidade). Depois de aplicadas, as substituições são usadas no app inteiro.

Também é possível usar o Android Debug Bridge (adb) para ativar ou desativar substituições e determinar quais delas se aplicam ao app.

Ative ou desative as substituições da seguinte maneira:

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

Para os dispositivos de referência, confira quais substituições se aplicam ao seu app:

adb shell dumpsys platform_compat | grep <package name>

A tabela a seguir lista as substituições disponíveis e orientações sobre como otimizar o app para que ele não precise depender de substituições. É possível adicionar flags de propriedade ao manifesto do app para desativar algumas substituições.

Substituições por app
Tipo	Nome	ID	Descrição
Capacidade de redimensionamento	FORCE_RESIZE_APP	174042936	Ignora o modo de compatibilidade de tamanho para o app nas mudanças de configuração.
	FORCE_NON_RESIZE_APP	181136395	Força o app a entrar no modo de compatibilidade de tamanho quando há mudanças na configuração.
Proporção	OVERRIDE_MIN_ASPECT_RATIO	174042980	Substituição intermediária que precisa ser ativada para aplicar todas as outras substituições de proporção.
	OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY	203647190	Se ativada (como é o padrão), limita o escopo da substituição a atividades somente na orientação retrato.
	OVERRIDE_MIN_ASPECT_RATIO_SMALL	349045028	Muda a proporção mínima para 4:3.
	OVERRIDE_MIN_ASPECT_RATIO_MEDIUM	180326845	Muda a proporção mínima para 3:2.
	OVERRIDE_MIN_ASPECT_RATIO_LARGE	180326787	Muda a proporção mínima para 16:9.
	OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN	208648326	Muda a proporção mínima para caber em 50% do tamanho de exibição (ou a proporção de tela dividida).
	OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN	218959984	Desativa a substituição de proporção mínima para que os apps sejam mostrados em tela cheia quando o dispositivo estiver na orientação retrato.
Orientação	OVERRIDE_ANY_ORIENTATION	265464455	Permite substituir qualquer orientação.
	OVERRIDE_ANY_ORIENTATION_TO_USER	310816437	Substitui as restrições de orientação, redimensionamento e proporção.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT	265452344	Muda a orientação para retrato quando uma atividade tem a orientação indefinida.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR	265451093	Muda a orientação para `nosensor` (para usar a orientação natural do dispositivo) quando uma atividade tem a orientação indefinida.
	OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE	266124927	Gira apps somente paisagem em 180 graus.
	OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA	265456536	Limita o escopo da substituição de orientação quando o app está conectado à câmera.
	OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION	255940284	Configura a tela para a orientação natural de paisagem fixa quando uma tarefa é mostrada em tela cheia (inclusive quando tiver o efeito letterbox).
	OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION	254631730	Ignora as solicitações de orientação do app para evitar repetições infinitas de rotação.
	OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED	273509367	Ignora solicitações de orientação repetidas enquanto uma atividade é reiniciada. Se o Android detectar que um app está pedindo pelo menos duas novas orientações em um segundo, o sistema considerará isso uma repetição infinita de rotação e aplicará a substituição.
	OVERRIDE_RESPECT_REQUESTED_ORIENTATION	236283604	Impede o efeito letterbox desativando a configuração feita pelo fabricante do dispositivo de ignorar a solicitação de orientação.
APIs de sandbox	NEVER_SANDBOX_DISPLAY_APIS	184838306	Impede a mudança do comportamento de todas as APIs Display.
	ALWAYS_SANDBOX_DISPLAY_APIS	185004937	Força as APIs `Display` a retornar os limites do app. As APIs `Display` retornam os limites da área de exibição lógica, mas às vezes o app presume que elas retornam os limites dele mesmo, o que leva a problemas na interface.`Display`
	OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS	237531167	Força as APIs `View` usadas a retornar os limites do app. As APIs `View` retornam os limites da área de exibição lógica, mas às vezes o app presume que elas retornam os limites dele mesmo, o que leva a problemas na interface.`View`
Compatibilidade com câmera	OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION	263959004	Desativa a rotação forçada. Por padrão, todos os apps de câmera com orientação fixa são girados à força quando a visualização da câmera está aberta.
	OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH	264304459	Remove a atualização forçada padrão aplicada quando uma visualização da câmera é forçada a girar.
	OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE	264301586	Muda a atualização forçada para uma atualização suave quando uma visualização da câmera é forçada a girar, o que ajuda a preservar o estado durante a rotação forçada. Por padrão, o Android aplica uma atualização forçada quando a visualização da câmera é girada à força. A atualização forçada pode causar problemas em alguns apps, que perdem o estado ou ficam ocultos, dependendo de como armazenam o estado anterior em cache.
	OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT	250678880	Corta o buffer de imagem na câmera frontal interna. Se a substituição for desativada, o corte da câmera frontal interna será removido e o campo de visão da visualização da câmera aumentará. Por padrão, em alguns dobráveis (consulte os dispositivos de referência), o sistema corta a visualização de todos os apps de câmera ao usar a câmera frontal interna.
Diversos	OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS	263259275	Impede que o app seja ocultado quando perder o foco no modo de tela dividida. O app aguarda receber o foco antes de mostrar o conteúdo, o que pode fazer com que o aplicativo congele ou seja ocultado. A substituição permite que o Android envie um evento de foco falso ao app, o que instrui o app a começar a mostrar o conteúdo de novo.

FORCE_RESIZE_APP

Força os pacotes aos quais a substituição é aplicada a serem redimensionáveis e capazes de entrar no modo de várias janelas. Isso se aplica a todos os tamanhos de tela.

Como os apps podem ter o mesmo resultado da substituição

No manifesto do app, defina o atributo android:resizeableActivity como true.

Como otimizar apps

Use layouts responsivos/adaptáveis para permitir que os apps se adaptem a todos os tamanhos de tela e proporções. Consulte Suporte a diferentes tamanhos de tela.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição e tornar o app redimensionável:

adb shell am compat enable FORCE_RESIZE_APP <package>

Para remover a substituição:

adb shell am compat disable FORCE_RESIZE_APP <package>

Observação: os comandos só aplicam ou removem a substituição temporariamente.

FORCE_NON_RESIZE_APP

Força os pacotes aos quais a substituição é aplicada a não serem redimensionáveis e entrarem no modo de compatibilidade de tamanho quando houver mudanças na configuração. Isso se aplica a todos os tamanhos de tela.

Como os apps podem ter o mesmo resultado da substituição

Defina o atributo android:resizeableActivity e a flag de metadados android.supports_size_changes como false no manifesto do app e declare uma restrição de orientação ou proporção.

Como otimizar apps

Todos os apps que se comportam bem quando redimensionados precisam ter android:resizeableActivity ou android.supports_size_changes definido como true. Outros apps precisam ser aprimorados para ter um bom comportamento quando redimensionados. Consulte android:resizeableActivity.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição e tornar o app não redimensionável:

adb shell am compat enable FORCE_NON_RESIZE_APP <package>

Para remover a substituição:

adb shell am compat disable FORCE_NON_RESIZE_APP <package>

Observação: os comandos só aplicam ou removem a substituição temporariamente.

OVERRIDE_MIN_ASPECT_RATIO

O responsável por todas as substituições que forçam uma determinada proporção mínima.

Como os apps podem ter o mesmo resultado da substituição

Defina android:minAspectRatio no nível da atividade ou do app.

Como otimizar apps

Não configure restrições de proporção no seu app. Confira se ele oferece suporte a diferentes tamanhos de tela. Use classes de tamanho de janela para oferecer suporte a diferentes layouts com base no espaço que seu app ocupa na tela. Consulte as APIs Compose WindowSizeClass e View WindowSizeClass.

Como desativar ou recusar a substituição

Especifique uma restrição de proporção ou defina a flag de propriedade PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO <package>

Observação: os comandos só aplicam ou removem a substituição temporariamente.

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

Restringe as configurações de apps que forçam uma determinada proporção mínima para atividades com orientação apenas de retrato. É ativado por padrão e só entra em vigor se OVERRIDE_MIN_ASPECT_RATIO também estiver ativado.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Observação: os comandos só aplicam ou removem a substituição temporariamente.

OVERRIDE_MIN_ASPECT_RATIO_SMALL

Configura a proporção mínima da atividade como um valor pequeno (4:3).

Como os apps podem ter o mesmo resultado da substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como otimizar apps

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como desativar ou recusar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Flags de propriedade para ajustar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_SMALL <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_SMALL <package>

Observação: os comandos só aplicam ou removem a substituição temporariamente.

OVERRIDE_MIN_ASPECT_RATIO_MEDIUM

Configura a proporção mínima da atividade como um valor médio (3:2).

Como os apps podem ter o mesmo resultado da substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como otimizar apps

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como desativar ou recusar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Flags de propriedade para ajustar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Observação: os comandos só aplicam ou removem a substituição temporariamente.

OVERRIDE_MIN_ASPECT_RATIO_LARGE

Configura a proporção mínima da atividade como um valor alto (16:9).

Como os apps podem ter o mesmo resultado da substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como otimizar apps

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como desativar ou recusar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Flags de propriedade para ajustar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>`

Observação: os comandos só aplicam ou removem a substituição temporariamente.

OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN

Permite o uso da proporção de tela dividida. Possibilita que um app use todo o espaço disponível no modo de tela dividida, evitando o efeito letterbox.

Como os apps podem ter o mesmo resultado da substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como otimizar apps

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como desativar ou recusar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Flags de propriedade para ajustar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Observação: os comandos só aplicam ou removem a substituição temporariamente.

OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN

Desativa a substituição de proporção mínima em tela cheia com orientação retrato para usar todo o espaço disponível na tela.

Como os apps podem ter o mesmo resultado da substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como otimizar apps

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Como desativar ou recusar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Flags de propriedade para ajustar a substituição

Consulte OVERRIDE_MIN_ASPECT_RATIO.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Observação: os comandos só aplicam ou removem a substituição temporariamente.

OVERRIDE_ANY_ORIENTATION

Permite que as seguintes substituições modifiquem qualquer orientação:

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

Como os apps podem ter o mesmo resultado da substituição

Defina o atributo de manifesto activity:screenOrientation ou use a API Activity#setRequestedOrientation().

Como otimizar apps

O app precisa oferecer suporte a todas as orientações. Uma mudança de orientação é uma alteração de configuração, que pode ser realizada de duas formas: deixando o sistema destruir e recriar o app ou gerenciando as mudanças de configuração por conta própria. Se você gerenciar as mudanças de configuração, o estado do app poderá ser mantido usando ViewModel. Em casos muito específicos, é possível restringir a orientação apenas em telas pequenas. No entanto, fazer isso pode não redimensionar bem e não permitir que o usuário gire o app conforme necessário. No Android 12L e versões mais recentes, a orientação fixa pode ser substituída pela configuração do dispositivo. Para mais informações sobre como processar mudanças de configuração e oferecer suporte a todas as orientações, consulte Processar mudanças de configuração, Visão geral do ViewModel e Orientação restrita do app em smartphones, mas não em dispositivos de tela grande.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_ANY_ORIENTATION <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_ANY_ORIENTATION <package>

Observação: os comandos só aplicam ou removem a substituição temporariamente.

OVERRIDE_ANY_ORIENTATION_TO_USER

Permite que o app preencha o espaço de exibição disponível. Substitui todas as restrições de orientação, redimensionamento e proporção especificadas no manifesto do app. Também ignora chamadas para Activity#setRequestedOrientation() ou Activity#getRequestedOrientation().

Como os apps podem ter o mesmo resultado da substituição

Não defina o atributo android:screenOrientation do manifesto ou defina o atributo como "user".
Defina o atributo android:resizeableActivity do manifesto como true.

Observação: as configurações de android:minAspectRatio e android:maxAspectRatio serão ignoradas se resizeableActivity for definido como true.
Em telas pequenas, para oferecer suporte ao redimensionamento de apps e desativar o modo de várias janelas com android:resizeableActivity=false, defina a flag de metadados android.supports_size_changes como true. Não defina minAspectRatio e maxAspectRatio.

Observação: no Android 12 (API de nível 31), todos os apps são executados no modo de várias janelas em telas grandes (classe de tamanho de janela média ou expandida) independente da configuração do app. Consulte Ofereça suporte ao modo de várias janelas.

Como otimizar apps

Ative o app para oferecer suporte a todas as orientações. Não defina uma especificação screenOrientation no manifesto do app. Para oferecer suporte ao redimensionamento de apps, ao modo de várias janelas e a todas as proporções da tela, defina o atributo android:resizeableActivity no manifesto do app como true. Consulte Suporte a diferentes tamanhos de tela.

Modo de compatibilidade do dispositivo Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Android 16

Desativar

Declarar propriedade do manifesto

Dispositivos de referência

Problemas comuns de compatibilidade

Letterboxing

Problema

Um app restrito à orientação retrato não pode ser usado em um dispositivo em modo paisagem.

Otimização

O app oferece suporte a todas as orientações de dispositivo.

Solução alternativa para compatibilidade

Modo de compatibilidade de tamanho

Problema

Um app não redimensionável falha no modo de várias janelas.

Otimização

O app funciona em todos os tamanhos de janela.

Solução alternativa para compatibilidade

Um app restrito à orientação de retrato é mostrado com efeito letterbox na orientação paisagem, redimensionado pelo controle de reinicialização.

Modo de compatibilidade de exibição

Repetições intermitentes

Problema

Um app somente paisagem no modo retrato faz chamadas repetidas para Activity#setRequestedOrientation().

Otimização

O app processa mudanças de configuração e não tem restrições de orientação, dessa forma, não entra em uma repetição intermitente.

Solução alternativa para compatibilidade

Visualização da câmera

Problema

Visualização da câmera desalinhada e distorcida em uma tela grande dobrável.

Otimização

Visualização da câmera alinhada e dimensionada corretamente em todas as orientações do dispositivo.

Solução alternativa para compatibilidade

Tablet: rotação forçada do app restrito a modo retrato.

Dispositivo dobrável: rotação forçada do app restrito ao modo retrato. O app também tem efeito letterbox.

APIs usadas indevidamente com frequência

Problema

Uma API descontinuada calcula de forma incorreta os limites do app. O conteúdo do app sai da tela.

Otimização

A API calcula corretamente as métricas da janela do app.

Solução alternativa para compatibilidade

Atividades transparentes

Problema

A caixa de diálogo foi posicionada incorretamente porque a atividade foi iniciada em um trampolim.

Otimização

Bordas arredondadas

Caixa de diálogo com cantos arredondados posicionada corretamente sobre a atividade de inicialização visível.

Solução alternativa para compatibilidade

Jogos do Unity

Problema

O jogo perde o foco no modo de várias janelas e é renderizado como uma janela preta.

Otimização

O jogo renderiza conteúdo corretamente no modo de várias janelas, mesmo quando não está em foco.

Solução alternativa para compatibilidade

Modo janela para computador

Os apps com orientação bloqueada ainda podem ser redimensionados livremente.

As atividades declaradas como não redimensionáveis têm a interface dimensionada.

Prévia da câmera em janelas de computador

Redimensionar uma janela com um visor de câmera

Testar um app para verificar problemas de compatibilidade

Efeito letterbox

Kotlin

Java

Kotlin

Java

Substituições por app

Substituições por app do usuário

Substituições por app no dispositivo

FORCE_RESIZE_APP

Como os apps podem ter o mesmo resultado da substituição

Como otimizar apps

Como desativar ou recusar a substituição

Flags de propriedade para ajustar a substituição

Comandos adb para testar a substituição

FORCE_NON_RESIZE_APP

Como os apps podem ter o mesmo resultado da substituição

Como otimizar apps

Como desativar ou recusar a substituição

Flags de propriedade para ajustar a substituição

Comandos adb para testar a substituição

OVERRIDE_MIN_ASPECT_RATIO

Modo de compatibilidade do dispositivo

Um app somente paisagem no modo retrato faz chamadas repetidas para `Activity#setRequestedOrientation()`.