Guia de configuração da compatibilidade de apps com telas grandes

A página oferece um guia de configuração abrangente e um índice para sobreposições de configuração de compatibilidade de apps para telas grandes do Android.

Display

Esta seção lista todas as configurações que afetam a configuração no nível da exibição.

Nome Local Tipo Padrão
ignoreOrientationRequest display_settings.xml config false
true para telas grandes (com 600 dp ou mais)
Descrição
: permite a rotação livre de atividades de orientação fixa no display especificado.
Exemplo: 
          <display-settings>
              <config identifier="0" />
              <display
                  name="<display's uniqueId>"
                  ignoreOrientationRequest="true"/>
          </display-settings>

Caso de uso ou contexto
: a tela ignora a orientação solicitada de todos os apps, e o app fica com efeito letterbox.
Usado em todos os dispositivos de tela grande e no Android Automotive OS. Esse é o padrão para todos os dispositivos de tela grande com smallestScreenWidthDp >= 600dp no Android 16 e versões mais recentes.
config_letterboxIsDisplayRotationImmersiveAppCompatPolicyEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Ativa a política de compatibilidade de rotação para apps imersivos que impede a rotação automática para uma orientação de tela não ideal enquanto está em tela cheia. Isso é necessário porque apps imersivos, como jogos, geralmente não são otimizados para todas as orientações e podem ter uma experiência do usuário ruim quando girados. Além disso, alguns jogos dependem de sensores para a jogabilidade. Assim, os usuários podem acionar essas rotações acidentalmente quando a rotação automática está ativada.
Aplicável apenas se ignoreOrientationRequest estiver ativado.

Caso de uso ou contexto
Bloqueia a rotação para apps imersivos.

Proporção

Esta seção lista todas as configurações que afetam a configuração da janela no nível da atividade para proporção da tela.

Nome Local Tipo Padrão
config_fixedOrientationLetterboxAspectRatio frameworks/base/core/res/res/values/config.xml Float 0.0
Descrição
: configura a proporção de corte de letterbox para orientação fixa. Valores menores ou iguais a 1.0 são ignorados.

Caso de uso ou contexto
: configura a proporção padrão do dispositivo que funciona para a maioria dos apps com efeito letterbox. Geralmente mais próximo de uma proporção de tela quadrada.
config_letterboxIsSplitScreenAspectRatioForUnresizableAppsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se a proporção da tela dividida será usada como padrão para apps não redimensionáveis.

Caso de uso ou contexto
A maioria dos apps não redimensionáveis espera um layout de smartphone candybar na vertical.
config_letterboxIsDisplayAspectRatioForFixedOrientationLetterboxEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se a proporção da tela será usada como padrão para todos os apps com efeito letterbox.

Caso de uso ou contexto
Uma configuração para usar programaticamente a proporção da tela em vez de configurar um valor de ponto flutuante.

Câmera

Esta seção lista todas as configurações que afetam os apps no retorno de chamada de onCameraOpened. Essas configurações podem afetar a tela, a atividade e a configuração da câmera.

Nome Local Tipo Padrão
config_isWindowManagerCameraCompatTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
: ativa o tratamento de compatibilidade da câmera para problemas causados por incompatibilidade de orientação entre buffers da câmera e uma janela do app.
Isso inclui a rotação forçada de atividades de orientação fixa conectadas à câmera em tela cheia e mostrando uma dica na tela dividida.
O tratamento de rotação forçada pode ser desativado pela substituição por app: OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Caso de uso ou contexto
Corrige visualizações da câmera giradas ao forçar a rotação da tela para corresponder à orientação solicitada do app.
config_isWindowManagerCameraCompatSplitScreenAspectRatioEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se uma atividade usa a proporção da tela dividida quando o tratamento de compatibilidade da câmera está ativado e a atividade está conectada à câmera em tela cheia.

Caso de uso ou contexto
Corrige visualizações esticadas da câmera ao fazer letterboxing da atividade para uma proporção semelhante a uma barra de chocolate.
Geralmente usado com o tratamento de rotação forçada ativado (config_isWindowManagerCameraCompatTreatmentEnabled e camera.enable_landscape_to_portrait) em dispositivos no modo paisagem para corrigir problemas de compatibilidade de câmera esticada simulando uma proporção semelhante a um candybar no modo retrato para a atividade.
camera.enable_landscape_to_portrait Propriedade do sistema Bool false
Descrição
: controla o tratamento OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT.
Força a saída da câmera a ser cortada e girada em 90 graus em câmeras com orientação natural paisagem para simular a orientação natural retrato. A orientação informada do sensor da câmera é retrato para todas as câmeras de paisagem no dispositivo. Muitos apps não processam essa situação e mostram imagens esticadas.

Caso de uso ou contexto
Ativa o tratamento de rotação e corte da HAL da câmera. Para mais informações sobre o tratamento, consulte Girar, cortar, dimensionar.
Adicione o seguinte ao arquivo mk no tempo de build: PRODUCT_PROPERTY_OVERRIDES += camera.enable_landscape_to_portrait=true
Esse tratamento exige que o dispositivo ofereça suporte a SCALER_ROTATE_AND_CROP na HAL. Consulte CameraCharacteristics#SCALER_AVAILABLE_ROTATE_AND_CROP_MODES.
Para orientações sobre a implementação específica do HAL para SCALER_ROTATE_AND_CROP, consulte metadata_definitions.xml.
config_isCameraCompatSimulateRequestedOrientationTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool true
Descrição
Indica se o tratamento de compatibilidade da câmera, que simula a orientação solicitada de um app, está ativado. O objetivo do tratamento é reduzir problemas causados por uma incompatibilidade de orientação entre o buffer da câmera e a janela do app. Isso inclui atividades de orientação fixa com letterboxing conectadas à câmera, corte do buffer da câmera (girar e cortar) e isolamento da rotação da tela para corresponder à orientação esperada do app.

Caso de uso ou contexto
Simular a orientação solicitada para atividades da câmera em:
  • Modo de janela de forma livre
  • Orientação fixa, exceto nos modos locked ou nosensor

No Android 17 e versões mais recentes, essa configuração desativa o tratamento de rotação forçada de config_isWindowManagerCameraCompatTreatmentEnabled e unifica as políticas de sandbox de rotação da tela, letterboxing e rotação e corte da câmera para apps de câmera de orientação fixa.
config_isCameraCompatSimReqOrientationLandscapeTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Indica se o tratamento de compatibilidade da câmera que simula a orientação solicitada de um app está ativado para câmeras de paisagem. O objetivo do tratamento é reduzir problemas causados por apps que codificam sensores de câmera retrato. O tratamento inclui letterboxing de atividades de orientação fixa conectadas à câmera, corte do buffer da câmera (girar e cortar), orientação do sensor para retrato e isolamento da rotação da tela para corresponder à orientação esperada do app.

Caso de uso ou contexto
No Android 17 e versões mais recentes, esse tratamento é o mesmo que o tratamento de simulação da orientação solicitada para config_isCameraCompatSimulateRequestedOrientationTreatmentEnabled, mas para dispositivos com câmeras orientadas para paisagem.

Segundo plano e interface

Esta seção lista todas as configurações aplicadas à superfície da camada letterbox para personalização da interface ou no nível da atividade.

Nome Local Tipo Padrão
config_letterboxActivityCornersRadius frameworks/base/core/res/res/values/config.xml Integer 0
Descrição
Configura o raio do canto de uma atividade apresentada no modo letterbox. Valores menores que 0 ativam cantos arredondados com um raio igual ao mínimo entre os raios dos cantos inferiores do dispositivo. Um valor padrão de 0 desativa a lógica de cantos arredondados em AppCompatLetterboxPolicy.

Caso de uso ou contexto
Geralmente configurado para corresponder aos cantos arredondados do dispositivo físico.
config_letterboxIsEnabledForTranslucentActivities frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se um comportamento específico para o letterboxing de atividades translúcidas está ativado.

Caso de uso ou contexto
Permite que atividades ou modais translúcidos sejam letterboxed e restringidos na configuração de atividade letterboxed. A política se aplica em TransparentPolicy.
config_isCompatFakeFocusEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se o envio de foco falso de compatibilidade para atividades retomadas em tela dividida está ativado.
Isso é necessário porque alguns mecanismos de jogos esperam receber o foco antes de mostrar o conteúdo do app, que não é fornecido por padrão nos modos de várias janelas.

Caso de uso ou contexto
Uma flag legada para aplicar o tratamento de compatibilidade aos mecanismos de jogos do Unity para apps que ficam pretos depois de entrar no modo de tela dividida e são mostrados apenas depois que o usuário toca e foca o app.
config_letterboxBackgroundType frameworks/base/core/res/res/values/config.xml Integer 0
Descrição
Configura a aparência do canto do plano de fundo da letterbox:
  • 0: plano de fundo sólido usando a cor especificada em R.color.config_letterboxBackgroundColor.
  • 1: cor especificada em R.attr.colorBackground para o aplicativo com efeito letterbox.
  • 2: cor especificada em R.attr.colorBackgroundFloating para o aplicativo com efeito letterbox.
  • 3: plano de fundo com desfoque escurecido ou tela escura. Pelo menos um dos seguintes parâmetros precisa ser maior que 0: config_letterboxBackgroundWallpaperBlurRadius ou config_letterboxBackgroundWallpaperDarkScrimAlpha. Se não for esse o caso ou se um raio de desfoque for fornecido, mas o desfoque não for compatível com o dispositivo e essa opção estiver selecionada, a implementação será padrão para a opção 0. Se o valor fornecido estiver fora desse intervalo, a opção 0 será presumida.


Caso de uso ou contexto
Esse recurso não foi lançado devido a problemas de desempenho. Os OEMs podem criar a própria implementação desse recurso, mas o AOSP não vai lidar com bugs.
config_letterboxBackgroundColor frameworks/base/core/res/res/values/config.xml Color @color/system_neutral1_1000
Descrição
: configura a cor do plano de fundo da letterbox se uma das seguintes condições for true:
  • A opção 0 está selecionada para R.integer.config_letterboxBackgroundType.
  • A opção 1 está selecionada para R.integer.config_letterboxBackgroundType e R.attr.colorBackground não foi especificado para o app.
  • A opção 2 está selecionada para R.integer.config_letterboxBackgroundType e R.attr.colorBackgroundFloating não foi especificado para o app.
  • A opção 3 está selecionada para R.integer.config_letterboxBackgroundType e o desfoque foi solicitado, mas não é compatível com o dispositivo, ou o alfa de tela escura e o raio de desfoque não foram fornecidos.


Caso de uso ou contexto
Esse recurso não foi lançado devido a problemas de desempenho. Os OEMs podem criar a própria implementação desse recurso, mas o AOSP não vai lidar com bugs.
config_letterboxBackgroundWallpaperBlurRadius frameworks/base/core/res/res/values/config.xml Dimen 38dp
Descrição
Configura o raio de desfoque para a opção 3 em R.integer.config_letterboxBackgroundType. Valores menores que 0 são ignorados e 0 é usado.

Caso de uso ou contexto
Esse recurso não foi lançado devido a problemas de desempenho. Os OEMs podem criar a própria implementação desse recurso, mas o AOSP não vai lidar com bugs.
config_letterboxBackgroundWallpaperDarkScrimAlpha frameworks/base/core/res/res/values/config.xml Float 0.54
Descrição
Configura o alfa de uma tela preta translúcida mostrada sobre o plano de fundo da caixa de correio do papel de parede quando a opção 3 é selecionada para R.integer.config_letterboxBackgroundType. Valores menores que 0 ou maiores ou iguais a 1 são ignorados, e 0.0 (transparente) é usado em vez disso.

Caso de uso ou contexto
Esse recurso não foi lançado devido a problemas de desempenho. Os OEMs podem criar a própria implementação desse recurso, mas o AOSP não vai lidar com bugs.
config_enableSelfKillRecoveryBetweenInternalDisplays frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Quando true, as movimentações de tela entre telas internas não são isentas da lógica de recuperação de autodestruição.

Caso de uso ou contexto
No Android 17 e versões mais recentes, o processo de recuperação de autodestruição é ativado apenas para movimentações de tela envolvendo monitores externos. No entanto, o processo também é eficaz em dispositivos dobráveis com densidades diferentes nas telas interna e externa. Essa configuração ativa o processo para esses dispositivos.

Acessibilidade e posicionamento

Esta seção lista todas as configurações aplicadas à configuração de janela no nível da atividade para acessibilidade.

Nome Local Tipo Padrão
config_letterboxIsHorizontalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se o reposicionamento horizontal de acessibilidade está ativado para apps com efeito letterbox no modo de janela em tela cheia.

Caso de uso ou contexto
Reposiciona um app no modo retrato para a esquerda ou direita para facilitar o acesso.
config_letterboxHorizontalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.5
Descrição
: configura a posição horizontal do centro da janela do app com efeito letterbox.
0 corresponde ao lado esquerdo da tela, e 1 corresponde ao lado direito.
Se o valor fornecido for menor que 0 ou maior que 1, ele será ignorado. Para uma postura que não seja de livro, a posição central (0.5) é usada. Para a postura do livro, a posição esquerda (0.0) é usada.

Caso de uso ou contexto
O padrão é o centro para um app retrato com efeito letterbox.
config_letterboxIsVerticalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se o reposicionamento vertical de acessibilidade está ativado para apps com efeito letterbox no modo de janela em tela cheia.

Caso de uso ou contexto
Reposiciona um app no modo paisagem para a parte de cima ou de baixo para facilitar o acesso.
config_letterboxVerticalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Descrição
: configura a posição vertical do centro da janela do app em formato letterbox.
O valor 0 corresponde à parte superior da tela, e 1 corresponde à parte inferior.
Se o valor fornecido for menor que 0 ou maior que 1, ele será ignorado. Para o modo que não é de mesa, a posição central (0.5) é usada. Para a postura de mesa, a posição superior (0.0) é usada.

Caso de uso ou contexto
Configurado para o centro em dispositivos de tela grande para um app em modo paisagem com efeito letterbox.
config_letterboxIsAutomaticReachabilityInBookModeEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se o posicionamento automático de alcance horizontal da postura de livro está ativado para apps com efeito letterbox no modo de janela em tela cheia.

Caso de uso ou contexto
Permite que um app com efeito letterbox na orientação retrato se mova entre a esquerda e a direita quando um dispositivo dobrável está na postura de livro.
config_letterboxBookModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Descrição
Configura a posição horizontal do centro da janela do app com efeito letterbox quando está na posição de livro.
0 corresponde ao lado esquerdo da tela, e 1 corresponde ao lado direito. Se o valor fornecido for menor que 0 ou maior que 1, ele será ignorado, e a posição à esquerda (0.0) será usada.

Caso de uso ou contexto
Um multiplicador de quanto a posição do app se move quando reposicionada na postura de livro.
config_letterboxDefaultPositionForBookModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
Descrição
Configura a posição horizontal padrão da janela do app com efeito letterbox quando a acessibilidade está ativada e um app está em tela cheia na orientação paisagem do dispositivo e na postura de livro. Quando a acessibilidade está ativada, a posição pode mudar entre esquerda, centro e direita:
  • Opção 0: esquerda
  • Opção 1: centralizar
  • Opção 2: direita
Se o valor fornecido estiver fora desse intervalo, a opção 0 (esquerda) será assumida.

Caso de uso ou contexto
A posição padrão em que o app é colocado no modo livro.
config_letterboxTabletopModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Descrição
: configura a posição vertical do centro da janela do app com efeito letterbox quando em postura de mesa.
O valor 0 corresponde à parte superior da tela, e 1 corresponde à parte inferior. Se o valor fornecido for menor que 0 ou maior que 1, ele será ignorado, e a posição superior 0.0 será usada.

Caso de uso ou contexto
Um multiplicador de quanto a posição do app se move em um dispositivo dobrável quando está na postura de mesa.
config_letterboxDefaultPositionForTabletopModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
Descrição
Configura a posição vertical padrão da janela do app com efeito letterbox quando a acessibilidade está ativada e um app está em tela cheia na orientação retrato do dispositivo e na postura de mesa. Quando a capacidade de alcance está ativada, a posição pode mudar entre cima, centro e baixo. Essa configuração define a padrão:
  • Opção 0: parte de cima
  • Opção 1: centralizar
  • Opção 2: parte de baixo
Se o valor fornecido estiver fora desse intervalo, a opção 0 (acima) será assumida.

Caso de uso ou contexto
A posição padrão em que o app é colocado no modo de mesa.

Configurações

Esta seção lista todas as configurações para personalizar e ativar as configurações de proporção da tela do usuário em Configurações > Apps > Proporção da tela.

Nome Local Tipo Padrão
config_appCompatUserAppAspectRatioSettingsIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se as configurações de substituição da proporção da tela por app estão ativadas.

Caso de uso ou contexto
Ativa o recurso Configurações de proporção da tela em Configurações > Apps > Proporção da tela.
config_appCompatUserAppAspectRatioFullscreenIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se a opção de substituição de tela cheia por app está ativada nas configurações de proporção da tela do usuário.

Caso de uso ou contexto
Ativa a opção Tela cheia no recurso configurações de proporção da tela do usuário.
Essa configuração ignora as restrições de não redimensionamento, proporção e orientação de um app.
config_userAspectRatioOverrideEntries packages/apps/Settings/res/values/config.xml string-array Todas as opções são ativadas por padrão.
Descrição
: configura a tela de configurações de proporção da tela do app e as opções de substituição da proporção da tela do usuário. Precisa ter o mesmo comprimento e ordem de config_userAspectRatioOverrideValues.
Se houver mudanças, atualize também a lógica de backup e restauração para escolher o valor mais próximo em UserAspectRatioBackupManager.java.

Caso de uso ou contexto
Mapeamentos para as strings mostradas em Configurações.
config_userAspectRatioOverrideValues packages/apps/Settings/res/values/config.xml integer-array Todas as strings do AOSP são usadas por padrão.
Descrição
: configura a tela de configurações de proporção da tela do app e as opções de substituição da proporção da tela do usuário. Precisa ter o mesmo comprimento e ordem de config_userAspectRatioOverrideEntries. Os valores precisam corresponder a PackageManager.UserMinAspectRatio.
Se for alterado, atualize também a lógica de backup e restauração para escolher o valor mais próximo em UserAspectRatioBackupManager.java.

Caso de uso ou contexto
Mapeamentos das opções para o back-end PackageManager.UserMinAspectRatio:
  • Padrão do app: 0
  • Tela dividida: 1
  • Proporção da tela: 2
  • 4:3 - 3
  • 16:9: 4
  • 3:2 - 5
  • Tela cheia: 6
Elementos gráficos estáticos com tema claro packages/apps/Settings/res/drawable/ic_app_aspect_ratio_<option>.xml vector Recursos dobráveis no modo paisagem
Descrição
Configura os elementos combináveis disponíveis:


Caso de uso ou contexto
Imagens estáticas com tema claro em cada opção em Configurações > Informações do app > Proporção.
Elementos gráficos estáticos com tema escuro packages/apps/Settings/res/drawable-night/ic_app_aspect_ratio_<option>.xml vector Recursos dobráveis no modo paisagem
Descrição
Configura os elementos combináveis disponíveis:


Caso de uso ou contexto
Imagens estáticas com tema escuro em cada opção em Configurações > Informações do app > Proporção da tela.
Elemento combinável dinâmico
user_aspect_ratio_education.json		 packages/apps/Settings/res/raw/user_aspect_ratio_education.json JSON Recurso dinâmico dobrável em modo paisagem
Descrição
Configura uma ilustração do Lottie em UserAspectRatioAppsPageProvider.

Caso de uso ou contexto
Uma animação na lista de apps: Configurações > Apps > Proporção de tela.

Educação

Esta seção lista todas as configurações para educar os usuários sobre os recursos de compatibilidade de apps.

Nome Local Tipo Padrão
config_letterboxIsEducationEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descrição
Configura se a educação em letterbox está ativada para apps em tela cheia com efeito letterbox.

Caso de uso ou contexto
Consulte a Figura 1 para um caso de uso da educação em letterbox para apps em tela cheia.
config_letterboxIsRestartDialogEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
Descrição
Configura se a caixa de diálogo de reinicialização estendida está ativada.

Caso de uso ou contexto
Consulte a Figura 2 para um caso de uso da caixa de diálogo de reinicialização estendida.
config_letterboxIsReachabilityEducationEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
Descrição
: configura se o ensino adicional sobre acessibilidade está ativado.

Caso de uso ou contexto
Consulte a Figura 3 para um caso de uso do ensino sobre acessibilidade.
config_isSizeCompatRestartButtonEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool true
Descrição
Configura se o botão de reinicialização da compatibilidade de tamanho está ativado.

Caso de uso ou contexto
Um botão de reinicialização para reiniciar a configuração de apps não redimensionáveis após mudanças no tamanho da janela, por exemplo, ao entrar na tela dividida ou girar a tela.
Consulte a Figura 4 para um caso de uso do botão de reinicialização da compatibilidade de tamanho.
config_letterboxRestartButtonHideTolerance frameworks/base/libs/WindowManager/Shell/res/values/config.xml Integer 100
Descrição
: configura a tolerância mínima da porcentagem de limites de atividade na tarefa para ocultar o botão de reinicialização da compatibilidade de tamanho. Valores menores que 0 ou maiores que 100 são ignorados.
100 é o valor padrão em que a atividade precisa se encaixar exatamente na tarefa para permitir que o botão de reinicialização da compatibilidade de tamanho seja ocultado. O valor 0 significa que o botão de reinicialização da compatibilidade de tamanho está sempre oculto.

Caso de uso ou contexto
Usado em dispositivos quase quadrados para ocultar o botão de reinicialização quando apps não redimensionáveis são girados pelo usuário, mas a reinicialização do app não melhora drasticamente a interface.

As imagens a seguir mostram casos de uso da sobreposição de educação:

Educação em letterbox para apps em tela cheia

Figura 1. Educação em letterbox para apps em tela cheia

Exemplo de uma caixa de diálogo de reinicialização estendida.

Figura 2. Caixa de diálogo de reinicialização estendida

Um exemplo de educação sobre acessibilidade.

Figura 3. Educação sobre acessibilidade.

Um exemplo do botão de reinicialização da compatibilidade de tamanho.

Figura 4. Botão de reinicialização da compatibilidade de tamanho.