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 os fabricantes de dispositivos mudem o comportamento do app para melhorar a experiência do usuário ou evitar falhas em dispositivos específicos.

Dispositivos de referência

Os dispositivos abaixo podem exigir substituições por app devido a configurações incomuns que não têm suporte de 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 é o modo retrato, os layouts do app e a visualização da câmera poderão ser incompatíveis com a tela do dispositivo.
• Dobráveis em modo paisagem:alguns dispositivos dobráveis, como o Pixel Fold, ficam na orientação de retrato quando dobrados, mas de paisagem quando desdobrados. Se os apps presumirem que a orientação desdobrada é de retrato, é provável que haja repetições pisantes ou problemas de layout.
• Smartphones dobráveis do tipo flip:os smartphones do tipo flip desdobrados normalmente estão na orientação retrato. No entanto, quando dobrados, os smartphones geralmente têm uma tela pequena na orientação paisagem. Os apps precisam identificar e acomodar as diferentes orientações das telas.

Problemas comuns de compatibilidade

Os apps apresentam problemas de compatibilidade com mais frequência devido a restrições de orientação e 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 do dispositivo geralmente são diferentes das de smartphones padrão, para os quais a maioria dos apps foi projetada.

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 o seguinte:

• 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 caber em janelas de dimensões variadas. No Android 11 (nível 30 da API) e versões anteriores, ela 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, ela especifica se os apps oferecem suporte ao modo de várias janelas em telas pequenas (sw menor que 600 dp). No Android 12 e versões mais recentes, os apps oferecem suporte ao modo de várias janelas em telas grandes (sw >= 600 dp), independente dessa configuração.

• maxAspectRatio: especifica a proporção máxima com suporte do app. Somente apps com a resizeableActivity definida como false podem definir maxAspectRatio.

• minAspectRatio: especifica a proporção mínima compatível com o app. Somente apps com resizeableActivity definido como false podem definir minAspectRatio.

cancel

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. Remova todas as restrições de orientação e proporção fixa dos layouts e do arquivo de manifesto do app.

check_circle

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 executado em uma janela em que não ofereça suporte diretamente ao tamanho ou à orientação da janela, o Android vai aplicar o efeito letterbox para preservar a continuidade.

No Android 12 (nível 31 da API) e no 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 o app se beneficie das melhorias.

O Android 12 (nível 31 da API) apresenta 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, tornando 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 do modo de compatibilidade de tamanho para que os usuários o reconheçam melhor.

O Android 13 (nível 33 da API) adiciona 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 inclui o efeito letterbox com um controle de reinicialização. O controle permite que os usuários reiniciem o app e mostrem de novo a 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.

cancel

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 tamanhos de tela diferentes e Suporte a várias janelas.

check_circle

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 melhorada redimensionando o app 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, recriando a atividade e redesenhando a tela. Consulte também Visão geral dos processos e threads.

warning

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

Repetições intermitentes

Quando um app não oferece suporte a todas as orientações da tela, ele pode solicitar novas orientações repetidamente quando ocorre uma 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 podem configurar os dispositivos para ignorar restrições de orientação especificadas pelos apps e usar as restrições para aplicar os 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 programaticamente a orientação chamando Activity#setRequestedOrientation(). A chamada vai acionar uma reinicialização do app se ele não estiver processando as mudanças de configuração. Consulte Gerenciar mudanças de configuração. Após a reinicialização, as restrições de orientação do app são ignoradas novamente, o app repete a chamada para setRequestedOrientation(), a chamada aciona uma reinicialização do app e assim por diante, em uma repetição contínua.

Você também pode encontrar isso quando a orientação natural (a orientação normal, conforme determinada pelo Android) de uma tela de dispositivo é de paisagem (ou seja, chamar Display#getRotation() retorna Surface.ROTATION_0, enquanto o dispositivo tem 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 esse nem sempre é o caso, 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 conferir 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á verificar novamente a rotação da tela, receber um valor de ROTATION_0, chamar setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT) e continuar o loop infinito.

cancel

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(), já que 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 indicadores não relacionados ao tamanho da janela atual, como Display#getRotation(), a presença de uma FoldingFeature ou APIs descontinuadas.

check_circle

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() nas seguintes 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 ocorreu 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.

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 tablets, laptops e telas dobráveis.

Problema

O Documento de definição de compatibilidade do Android afirma que um sensor de imagem de câmera "PRECISA estar orientado para que a dimensão longa da câmera alinhada com a 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 em smartphones padrão. No entanto, a orientação natural de tablets, laptops e sensores de câmera pode ser um paisagem. Além disso, novos formatos, como dobráveis, podem ter várias orientações naturais e vários 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 (para dobráveis) pode causar uma visualização de câmera desalinhada ou distorcida.

cancel

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 apresentar uma visualização da câmera alinhada e dimensionada corretamente. Os apps precisam calcular a rotação do dispositivo, a rotação 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.

check_circle

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 modo retrato de apps restritos ao modo retrato com a orientação natural do dispositivo, 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 soluções específicas incluem:

• Forçar a rotação das visualizações da câmera em apps restritos ao modo 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 poderão 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 dispositivos de referência), a janela de retrato do app é girada para o modo retrato em tela cheia para se alinhar à orientação natural do dispositivo. O app ocupa a tela cheia após a rotação forçada.

  

  warning

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

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

  

  warning

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

• Recorte da câmera frontal interna:o sensor da câmera frontal interna em 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 câmera frontal interna (em modo paisagem) para que o sensor capture uma visão oposta à orientação do dispositivo.

• Forçar a atualização das visualizações da câmera:o sistema alterna entre os métodos de atividade onStop() e onStart() (por padrão) ou onPause() e onResume() (aplicado pela substituição OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE por app) após a rotação forçada para garantir que a visualização da câmera seja exibida corretamente.

• Dimensionamento da proporção:o sistema muda dinamicamente a proporção da visualização forçada da câmera para 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 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 projetadas para fins especiais que nem sempre são bem entendidos 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 por engano as APIs de visualização para fins especiais para conseguir 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, causando problemas de layout.

APIs Display descontinuadas e usadas indevidamente com frequência:

• getMetrics()
• getSize()
• getRealMetrics()
• getRealSize()
• getRectSize()
• getWidth()
• getHeight()

Para mais informações, consulte Suporte a várias janelas.

APIs de visualização usadas indevidamente:

• getWindowVisibleDisplayFrame()
• getLocationOnScreen()

cancel

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()

check_circle

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 o uso indevido das APIs View 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 é aplicado 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, por exemplo:

<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 as torna difíceis de gerenciar, porque a área de tela disponível pode mudar com base em mudanças de configuração, como rotação, dobrar e desdobrar do dispositivo e modo de várias janelas.

Problema

Uma atividade transparente precisa estar em conformidade com os limites da primeira atividade opaca abaixo da atividade transparente na pilha de atividades da tarefa. No entanto, uma atividade opaca que inicia uma caixa de diálogo de permissão pode ser um trampolim (uma atividade que inicia outra atividade e depois desaparece). Portanto, o sistema não consegue determinar os limites da atividade trampolim que iniciou a atividade da caixa de diálogo de permissão transparente.

cancel

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

Otimização

As atividades transparentes herdam as restrições da atividade mais opaca acima delas 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 da atividade. Por esse motivo, não inicie solicitações de permissão usando atividades trampolim.

Se uma atividade trampolim iniciar uma solicitação de permissão, talvez o usuário não consiga ver a caixa de diálogo de permissão, porque ela terá sido destruída antes de o usuário conseguir responder à caixa de diálogo. Além disso, as dimensões e a posição da atividade da 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 em segundo plano 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 à atividade quando configurado para isso 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, cabe a você decidir se vai aplicar ou não 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 geralmente usa LayoutParams.WRAP_CONTENT, em vez de LayoutParams.MATCH_PARENT.

check_circle

Caixa de diálogo com cantos arredondados posicionados 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é que o usuário responda à caixa de diálogo.

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 no Unity 2019.4 para oferecer suporte ao modo de várias janelas no Android. No entanto, a implementação inicial não reagiu corretamente ao ciclo de vida da atividade no modo de várias janelas, fazendo com que o UnityPlayer suspendesse a reprodução quando o app perdesse 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.

cancel

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.

check_circle

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.

Testar um app para verificar problemas de compatibilidade

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

• Streaming de dispositivos:para testar seu 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 Hedgehog: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:

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()
    }
}

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();
}

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

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

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

@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();
        });
    }
}

O ideal é executar esse tipo de teste somente até que ele seja aprovado e declare que as atividades do app ocupam todo o espaço de exibição disponível para o app. Teste o app em todos os tipos de dispositivos 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 adequar às dimensões de exibição, mesmo que resizeableActivity="false" seja especificado no manifesto do app.

Os fabricantes de dispositivos aplicam substituições para alguns ou 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 a apps nas configurações do dispositivo.

Substituições de usuário por app

No Android 14 e 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 dele 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.

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

• PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE (em inglês)

  Para desativar a substituição de compatibilidade de proporção 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 nas configurações do dispositivo. Os usuários não vão poder 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 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 foi removida da lista de opções de proporção nas configurações do dispositivo. Os usuários não poderão aplicar a substituição de tela cheia ao app.

  Definir essa propriedade como true não tem efeito.

Otimize o 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 na quantidade de espaço de exibição disponível.

Substituições por app do fabricante do dispositivo

Os fabricantes de dispositivos aplicam substituições por app em alguns dispositivos. Os dispositivos de referência podem aplicar algumas das substituições a uma variedade de apps por padrão.

Os apps podem desativar 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.

Você também pode usar o Android Debug Bridge (adb) para ativar ou desativar substituições e determinar quais substituições 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, verifique quais substituições se aplicam ao seu app:

adb shell dumpsys platform_compat | grep <package name>

A tabela abaixo lista as substituições disponíveis e orientações sobre como otimizar seu 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.

FORCE_RESIZE_APP

Força os pacotes aos quais a substituição será aplicada a serem redimensionáveis. Não muda se o app pode ser colocado no modo de várias janelas, mas permite que ele seja redimensionado sem entrar no modo de compatibilidade de tamanho quando a tela é redimensionada.

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

No manifesto do app, defina o atributo android:resizeableActivity como true ou, para oferecer suporte ao redimensionamento e desativar o modo de várias janelas com android:resizeableActivity=false, defina a flag de metadados android.supports_size_changes 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 tamanhos de tela diferentes.

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 será aplicada a não serem redimensionáveis e entrarem no modo de compatibilidade de tamanho quando houver mudanças na configuração.

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 defina restrições de proporção no 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 o 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 do app que forçam uma determinada proporção mínima para atividades com orientação apenas de retrato. Ativada por padrão e só terá efeito se OVERRIDE_MIN_ASPECT_RATIO também estiver ativado.

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_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_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. Permite 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_UNDEFINED_ORIENTATION_TO_PORTRAIT

Ativa a orientação retrato para todas as atividades no pacote. A menos que a OVERRIDE_ANY_ORIENTATION esteja ativada, a substituição será usada somente quando nenhuma outra orientação fixa tiver sido especificada pela atividade.

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 mudança de configuração, que pode ser processada de duas maneiras: permitindo que o sistema destrua e recrie 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 retido usando ViewModel. Em casos muito limitados, é possível bloquear a orientação apenas em telas pequenas, embora isso possa não dimensionar tão bem quanto 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_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>

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

OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR

Ativa a orientação nosensor para todas as atividades no pacote. A menos que a OVERRIDE_ANY_ORIENTATION esteja ativada, a substituição será usada somente quando nenhuma outra orientação fixa tiver sido especificada pela atividade.

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

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como otimizar apps

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como desativar ou recusar a substituição

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Flags de propriedade para ajustar a substituição

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT. ```

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>

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

OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

Ativa a orientação reverseLandscape para todas as atividades no pacote. A menos que a OVERRIDE_ANY_ORIENTATION esteja ativada, a substituição será usada somente quando nenhuma outra orientação fixa tiver sido especificada pela atividade.

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

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como otimizar apps

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como desativar ou recusar a substituição

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Flags de propriedade para ajustar a substituição

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>

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

OVERRIDE_ANY_ORIENTATION

Permite que as substituições OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT, OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR e OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE possam substituir qualquer orientação.

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

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como otimizar apps

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como desativar ou recusar a substituição

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Flags de propriedade para ajustar a substituição

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

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_ORIENTATION_ONLY_FOR_CAMERA

Limita as substituições OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT, OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR e OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE para que entrem em vigor somente quando a conexão da câmera estiver ativa.

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

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como otimizar apps

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como desativar ou recusar a substituição

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Flags de propriedade para ajustar a substituição

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>

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

OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION

Restringe a orientação da tela para a de paisagem natural quando as seguintes condições são atendidas:

• A atividade está em tela cheia.
• A propriedade do componente de desativação PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE não está ativada.
• A configuração para ignorar a solicitação de orientação do fabricante do dispositivo está ativada para a tela
• A orientação natural da tela é paisagem.

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

Não aplicável. O problema precisa ser resolvido usando a lógica do aplicativo.

Como otimizar apps

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>

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

OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION

Ativa a política de compatibilidade que ignora a atualização da orientação do app em resposta à chamada Activity#setRequestedOrientation() quando o app é reiniciado ou tem um tratamento de compatibilidade de câmera ativo.

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

Defina a flag de propriedade PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION como true.

Como otimizar apps

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>

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

OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED

Ativa a política de compatibilidade que ignora a orientação solicitada de um app em resposta à chamada de Activity#setRequestedOrientation() mais de duas vezes em um segundo se uma atividade não tiver efeito letterbox na orientação fixa.

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

Não aplicável. O problema precisa ser resolvido usando a lógica do aplicativo.

Como otimizar apps

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_COMPAT_ALLOW_IGNORING_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>

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

OVERRIDE_RESPECT_REQUESTED_ORIENTATION

Exclui pacotes do comportamento de ignorar a solicitação de orientação, que pode ser ativado pelos fabricantes de dispositivos para uma área de exibição ou para a tela inteira.

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

Não aplicável. O problema precisa ser resolvido usando a lógica do aplicativo.

Como otimizar apps

Consulte OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Como desativar ou recusar a substituição

Não é possível recusar. Desativar a substituição pode ser perigoso se o app não for compatível com um dispositivo em que a configuração de ignorar a solicitação de orientação seja ativada pelo fabricante. Entre em contato com a equipe de Relações com desenvolvedores Android para desativar a substituição.

Flags de propriedade para ajustar a substituição

Não há flags de propriedade para essa substituição.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>

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

NEVER_SANDBOX_DISPLAY_APIS

Força os pacotes a nunca ter o sandbox da API Display aplicado a uma atividade com efeito letterbox ou modo de compatibilidade de tamanho. As APIs Display continuam fornecendo limites de área de exibição.

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

Declare atividades redimensionáveis definindo o atributo do manifesto android:resizeableActivity como true ou a flag de metadados android.supports_size_changes como true.

Como otimizar apps

Os apps que declaram ser totalmente redimensionáveis não podem depender do tamanho de exibição para posicionar elementos da interface. Migre seu app para APIs atualizadas que fornecem WindowMetrics. Se você estiver usando o Jetpack Compose, use a API WindowSizeClass para mostrar a interface com base na área que o app ocupa na tela atual. Consulte Classes de tamanho de janela.

Como desativar ou recusar a substituição

Não é possível recusar. Migre das APIs descontinuadas.

Flags de propriedade para ajustar a substituição

Não há flags de propriedade para essa substituição.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable NEVER_SANDBOX_DISPLAY_APIS <package>

Para remover a substituição:

adb shell am compat disable NEVER_SANDBOX_DISPLAY_APIS <package>

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

ALWAYS_SANDBOX_DISPLAY_APIS

Força os pacotes a sempre aplicar o sandbox da API Display, independente do modo de janelamento. As APIs Display sempre fornecem os limites do app.

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

Declare atividades não redimensionáveis definindo o atributo android:resizeableActivity como false ou a flag de metadados android.supports_size_changes como false.

Como otimizar apps

Os apps que declaram ser totalmente redimensionáveis não podem depender do tamanho de exibição para posicionar elementos da interface. Migre seu app de APIs descontinuadas para APIs atualizadas que fornecem WindowMetrics. Consulte WindowMetricsCalculator.

Como desativar ou recusar a substituição

Não é possível recusar. Migre das APIs descontinuadas.

Flags de propriedade para ajustar a substituição

Não há flags de propriedade para essa substituição.

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable ALWAYS_SANDBOX_DISPLAY_APIS <package>

Para remover a substituição:

adb shell am compat disable ALWAYS_SANDBOX_DISPLAY_APIS <package>

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

OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS

Força os pacotes a colocar as APIs View abaixo no sandbox para limites de atividade:

• getWindowVisibleDisplayFrame()
• getLocationOnScreen()

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

Resolva o problema no código do aplicativo usando APIs que forneçam os limites da janela do app e deslocamentos relativos à janela do app, em vez dos limites da tela e deslocamentos relativos à tela do dispositivo.

Como otimizar apps

Os apps precisam usar APIs View, considerando a possibilidade de aplicação do efeito letterbox e do modo de várias janelas. Consulte WindowMetricsCalculator.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>

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

OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION

Desativa a rotação forçada. Melhora a experiência do usuário em alguns apps.

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

Defina a flag de propriedade PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION como false.

Como otimizar apps

Não confie na orientação do sensor da câmera armazenada em cache ou nas informações do dispositivo. Para orientações sobre a compatibilidade da câmera, consulte Introdução ao visor da câmera e Suporte a superfícies redimensionáveis no app de câmera.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION como true.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para usar a substituição, que remove a rotação forçada:

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>

Para remover a substituição, que permite que a rotação forçada ocorra:

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>

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

OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH

Desativa a atualização de atividades após a rotação forçada. Melhora a experiência do usuário quando a atualização causa a perda de estado nos apps.

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

Defina a flag de propriedade PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH como false.

Como otimizar apps

Consulte OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH como true.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para usar a substituição, que remove a atualização da atividade:

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>

Para remover a substituição, que permite a atualização da atividade:

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>

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

OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE

Faz com que os pacotes a que é aplicada atualizem a atividade usando um ciclo onResume() → onPause() → onResume() em vez de onResume() → onStop() → onResume() após a compatibilidade da câmera forçar a rotação.

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

Defina a flag de propriedade PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE como true.

Como otimizar apps

Consulte OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>

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

OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT

Força a saída da câmera a ser cortada na orientação oposta quando a orientação retrato da câmera não se alinhar à orientação natural do dispositivo. Muitos apps não processam essa situação e mostram imagens esticadas.

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

Defina a flag de propriedade PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT como true.

Como otimizar apps

Consulte OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT como false.

Flags de propriedade para ajustar a substituição

<property android:name="android.camera.PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT"
  android:value="true|false"/>

Comandos adb para testar a substituição

Para usar a substituição, que aplica o corte da câmera frontal interna:

adb shell am compat enable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>

Para remover a substituição, que remove o corte da câmera frontal interna:

adb shell am compat disable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>

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

OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION

Impede que os apps desativem o compartilhamento de tela. Consulte Projeção de mídia. Implementado quando os apps usam a API createConfigForDefaultDisplay() de forma indevida para forçar a captura em tela cheia e comprometer a privacidade do usuário ao expor o conteúdo de notificações, que são capturadas em tela cheia, mas não com o compartilhamento de tela, e todos os apps, independente do modo de janela.

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

Permitir o comportamento de projeção de mídia padrão (implementado no Android 14, API de nível 34, com createScreenCaptureIntent()), que permite que os usuários decidam se querem compartilhar a tela cheia ou uma única janela do app, independente do modo de janelamento. Ou chame createScreenCaptureIntent(MediaProjectionConfig) com um argumento MediaProjectionConfig retornado de uma chamada para createConfigForUserChoice().

Como otimizar apps

Permitir que os usuários selecionem se querem compartilhar a tela inteira do dispositivo ou uma janela do app durante a projeção de mídia, que é o comportamento padrão a partir do Android 14.

Torne seu app redimensionável (resizeableActivity="true") para oferecer suporte ao modo de várias janelas.

Como desativar ou recusar a substituição

Devido à seriedade da privacidade do usuário, o app não pode desativar ou recusar essa substituição.

Flags de propriedade para ajustar a substituição

Nenhum.

Comandos adb para testar a substituição

Para aplicar a substituição, que cancela a desativação do compartilhamento de tela parcial pelo app (ou seja, ativa o compartilhamento de tela parcial):

adb shell am compat enable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>

Para remover a substituição, que permite que o app desative o compartilhamento de tela parcial:

adb shell am compat disable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>

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

OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS

Ativa o envio de foco falso para apps sem foco no modo de tela dividida. Alguns mecanismos de jogos esperam receber o foco antes de mostrar o conteúdo do app. O foco falso ajuda os apps a não ficarem ocultos quando são retomados e ainda não têm foco.

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

Defina a flag de propriedade PROPERTY_COMPAT_ENABLE_FAKE_FOCUS como true.

Como otimizar apps

Você poderá evitar esse problema se o app processar bem várias orientações e mudanças de configuração. Prepare o app para telas grandes seguindo as diretrizes de qualidade de apps para telas grandes.

Se você usa o mecanismo de jogo do Unity, faça upgrade 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.

Como desativar ou recusar a substituição

Defina a flag de propriedade PROPERTY_COMPAT_ENABLE_FAKE_FOCUS como false.

Flags de propriedade para ajustar a substituição

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

Comandos adb para testar a substituição

Para aplicar a substituição:

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>

Para remover a substituição:

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>

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

Outros recursos

• Diretrizes de qualidade de apps para telas grandes
• Diretrizes principais de qualidade de apps