Guía de configuración de la compatibilidad con apps para pantallas grandes

En esta página, se proporciona una guía de configuración y un índice completos para las superposiciones de configuración de compatibilidad de apps para pantallas grandes de Android.

Pantalla

En esta sección, se enumeran todos los parámetros de configuración que afectan la configuración a nivel de la pantalla.

Name Ubicación Tipo Predeterminado
ignoreOrientationRequest display_settings.xml config false
true para pantallas grandes (ancho mínimo >= 600 dp)
Descripción
Permite la rotación gratuita por parte del usuario de las actividades de orientación fija en la pantalla especificada.
Ejemplo: 
          <display-settings>
              <config identifier="0" />
              <display
                  name="<display's uniqueId>"
                  ignoreOrientationRequest="true"/>
          </display-settings>

Caso de uso o contexto
La pantalla ignora la orientación solicitada de todas las apps, y la app se muestra en formato letterbox.
Se usa en todos los dispositivos de pantalla grande y en el SO Android Automotive. Este es el valor predeterminado para todos los dispositivos de pantalla grande con smallestScreenWidthDp >= 600dp en Android 16 y versiones posteriores.
config_letterboxIsDisplayRotationImmersiveAppCompatPolicyEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Habilita la política de compatibilidad de rotación para las apps envolventes que evita la rotación automática a una orientación de pantalla no óptima mientras se está en pantalla completa. Esto es necesario porque las apps inmersivas, como los juegos, a menudo no están optimizadas para todas las orientaciones y pueden tener una UX deficiente cuando se rotan. Además, algunos juegos dependen de los sensores para la jugabilidad, por lo que los usuarios pueden activar esas rotaciones de forma accidental cuando la rotación automática está activada.
Solo se aplica si ignoreOrientationRequest está habilitado.

Caso de uso o contexto
Bloquea la rotación para las apps inmersivas.

Relación de aspecto

En esta sección, se enumeran todos los parámetros de configuración que afectan la configuración de la ventana a nivel de la actividad para la relación de aspecto.

Name Ubicación Tipo Predeterminado
config_fixedOrientationLetterboxAspectRatio frameworks/base/core/res/res/values/config.xml Float 0.0
Descripción
Configura la proporción de aspecto del letterboxing para la orientación fija. Se ignoran los valores menores o iguales que 1.0.

Caso de uso o contexto
Configura la relación de aspecto predeterminada del dispositivo que funciona para la mayoría de las apps con formato de buzón. Por lo general, se acerca más a una relación de aspecto cuadrada.
config_letterboxIsSplitScreenAspectRatioForUnresizableAppsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si se debe usar la relación de aspecto de pantalla dividida como relación de aspecto predeterminada para las apps que no se pueden cambiar de tamaño.

Caso de uso o contexto
La mayoría de las apps que no se pueden cambiar de tamaño esperan un diseño de teléfono con forma de barra de chocolate en orientación vertical.
config_letterboxIsDisplayAspectRatioForFixedOrientationLetterboxEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si se debe usar la relación de aspecto de la pantalla como relación de aspecto predeterminada para todas las apps con formato de buzón.

Caso de uso o contexto
Es una configuración para usar de forma programática la relación de aspecto de la pantalla en lugar de configurar un valor de número de punto flotante.

Cámara

En esta sección, se enumeran todos los parámetros de configuración que afectan a las apps cuando se realiza la devolución de llamada de onCameraOpened. Estos parámetros de configuración pueden afectar la pantalla, la actividad y la configuración de la cámara.

Name Ubicación Tipo Predeterminado
config_isWindowManagerCameraCompatTreatmentEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Habilita el tratamiento de compatibilidad de la cámara para los problemas causados por la falta de coincidencia de orientación entre los búferes de la cámara y la ventana de una app.
Esto incluye la rotación forzada de actividades de orientación fija conectadas a la cámara en pantalla completa y que muestran una sugerencia en pantalla dividida.
El tratamiento de rotación forzada se puede inhabilitar con la anulación por app: OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Caso de uso o contexto
Corrige las vistas previas de la cámara rotadas forzando la rotación de la pantalla para que coincida con la orientación solicitada de la app.
config_isWindowManagerCameraCompatSplitScreenAspectRatioEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si una actividad usa la relación de aspecto de pantalla dividida cuando se habilita el tratamiento de compatibilidad con la cámara y la actividad se conecta a la cámara en pantalla completa.

Caso de uso o contexto
Corrige las vistas previas de la cámara estiradas agregando letterboxing a la actividad para que tenga una relación de aspecto similar a la de una barra de chocolate.
Por lo general, se usa junto con el tratamiento de rotación forzada habilitado (config_isWindowManagerCameraCompatTreatmentEnabled y camera.enable_landscape_to_portrait) en dispositivos horizontales para solucionar problemas de compatibilidad de la cámara estirada simulando una relación de aspecto similar a la de un caramelo vertical para la actividad.
camera.enable_landscape_to_portrait Propiedad del sistema Bool false
Descripción
Puerta de acceso al tratamiento OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT.
Fuerza que la salida de la cámara se recorte y rote 90 grados en cámaras con orientación natural horizontal para simular la orientación natural vertical. La orientación del sensor de la cámara que se informa es vertical para todas las cámaras horizontales del dispositivo. Muchas apps no controlan esta situación y muestran imágenes estiradas.

Caso de uso o contexto
Habilita el tratamiento de rotación y recorte de la HAL de la cámara. Para obtener más información sobre el tratamiento, consulta Rotar, recortar y escalar.
Agrega lo siguiente a tu archivo .mk en el momento de la compilación: PRODUCT_PROPERTY_OVERRIDES += camera.enable_landscape_to_portrait=true
Este tratamiento requiere que el dispositivo admita SCALER_ROTATE_AND_CROP en la HAL. Consulta CameraCharacteristics#SCALER_AVAILABLE_ROTATE_AND_CROP_MODES.
Para obtener orientación sobre la implementación específica del HAL para SCALER_ROTATE_AND_CROP, consulta metadata_definitions.xml.

IU y segundo plano

En esta sección, se enumeran todos los parámetros de configuración aplicados a la superficie de la capa de letterbox para la personalización de la IU o a nivel de la actividad.

Name Ubicación Tipo Predeterminado
config_letterboxActivityCornersRadius frameworks/base/core/res/res/values/config.xml Integer 0
Descripción
Configura el radio de esquina para una actividad presentada en modo buzón. Los valores inferiores a 0 habilitan esquinas redondeadas con un radio igual al mínimo entre los radios de las esquinas inferiores del dispositivo. Un valor predeterminado de 0 desactiva la lógica de esquinas redondeadas en AppCompatLetterboxPolicy.

Caso de uso o contexto
Por lo general, se configura para que coincida con las esquinas redondeadas del dispositivo físico.
config_letterboxIsEnabledForTranslucentActivities frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si se habilita el comportamiento específico para el letterboxing de actividades translúcidas.

Caso de uso o contexto
Permite que las actividades o los modales translúcidos se muestren con letterboxing y se restrinjan dentro de la configuración de la actividad con letterboxing. La política se aplica en TransparentPolicy.
config_isCompatFakeFocusEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si está habilitado el envío de un enfoque falso de compatibilidad para las actividades reanudadas en pantalla dividida.
Esto es necesario porque algunos motores de juegos esperan hasta obtener el enfoque antes de dibujar el contenido de la app, que no se proporciona de forma predeterminada en los modos multiventana.

Caso de uso o contexto
Es un parámetro heredado para aplicar el tratamiento de compatibilidad a los motores de juegos de Unity para las apps que se vuelven negras después de ingresar al modo de pantalla dividida y se dibujan solo después de que el usuario presiona y enfoca la app.
config_letterboxBackgroundType frameworks/base/core/res/res/values/config.xml Integer 0
Descripción
Configura la apariencia de las esquinas del fondo de letterbox:
  • 0: Fondo sólido que usa el color especificado en R.color.config_letterboxBackgroundColor.
  • 1: Es el color especificado en R.attr.colorBackground para la aplicación con formato de buzón.
  • 2: Es el color especificado en R.attr.colorBackgroundFloating para la aplicación con formato de buzón.
  • 3: Fondo de pantalla con desenfoque atenuado o scrim oscuro. Al menos uno de los siguientes parámetros debe ser mayor que 0: config_letterboxBackgroundWallpaperBlurRadius o config_letterboxBackgroundWallpaperDarkScrimAlpha. Si no es así, o si se proporciona un radio de desenfoque, pero el dispositivo no admite el desenfoque y se selecciona esta opción, la implementación se establece de forma predeterminada en la opción 0. Si el valor proporcionado está fuera de este rango, se supone que se eligió la opción 0.


Caso de uso o contexto
Esta función no se lanzó debido a problemas de rendimiento existentes. Los OEM pueden crear su propia implementación de esta función, pero el AOSP no se encargará de solucionar ningún error.
config_letterboxBackgroundColor frameworks/base/core/res/res/values/config.xml Color @color/system_neutral1_1000
Descripción
Configura el color del fondo de letterbox si se cumple una de las siguientes condiciones:
true:
  • Se seleccionó la opción 0 para R.integer.config_letterboxBackgroundType.
  • Se selecciona la opción 1 para R.integer.config_letterboxBackgroundType y no se especifica R.attr.colorBackground para la app.
  • Se selecciona la opción 2 para R.integer.config_letterboxBackgroundType y no se especifica R.attr.colorBackgroundFloating para la app.
  • Se selecciona la opción 3 para R.integer.config_letterboxBackgroundType y se solicita desenfoque, pero no se admite en el dispositivo, o bien no se proporcionan el radio de desenfoque ni el valor alfa de la pantalla oscura.


Caso de uso o contexto
Esta función no se lanzó debido a problemas de rendimiento existentes. Los OEM pueden crear su propia implementación de esta función, pero el AOSP no se encargará de solucionar ningún error.
config_letterboxBackgroundWallpaperBlurRadius frameworks/base/core/res/res/values/config.xml Dimen 38dp
Descripción
Configura el radio de desenfoque para la opción 3 en R.integer.config_letterboxBackgroundType. Se ignoran los valores inferiores a 0 y se usa 0.

Caso de uso o contexto
Esta función no se lanzó debido a problemas de rendimiento existentes. Los OEM pueden crear su propia implementación de esta función, pero el AOSP no se encargará de solucionar ningún error.
config_letterboxBackgroundWallpaperDarkScrimAlpha frameworks/base/core/res/res/values/config.xml Float 0.54
Descripción
Configura el canal alfa de una pantalla negra translúcida que se muestra sobre el fondo de la pantalla de buzón del fondo de pantalla cuando se selecciona la opción 3 para R.integer.config_letterboxBackgroundType. Se ignoran los valores inferiores a 0 o superiores o iguales a 1, y se usa 0.0 (transparente) en su lugar.

Caso de uso o contexto
Esta función no se lanzó debido a problemas de rendimiento existentes. Los OEM pueden crear su propia implementación de esta función, pero el AOSP no se encargará de solucionar ningún error.

Alcance y posicionamiento

En esta sección, se enumeran todos los parámetros de configuración aplicados a la configuración de la ventana a nivel de la actividad para la accesibilidad.

Name Ubicación Tipo Predeterminado
config_letterboxIsHorizontalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si se habilita el reposicionamiento de accesibilidad horizontal para las apps en formato letterbox en el modo de ventanas de pantalla completa.

Caso de uso o contexto
Reposiciona una app vertical hacia la izquierda o la derecha para facilitar el acceso.
config_letterboxHorizontalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.5
Descripción
Configura la posición horizontal del centro de la ventana de la app con formato de buzón.
0 corresponde al lado izquierdo de la pantalla y 1 al lado derecho.
Si el valor proporcionado es menor que 0 o mayor que 1, se ignora. Para la posición que no es de libro, se usa la posición central (0.5). En el caso de la postura de libro, se usa la posición izquierda (0.0).

Caso de uso o contexto
De forma predeterminada, se centra en el caso de una app con formato de buzón vertical.
config_letterboxIsVerticalReachabilityEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si se habilita el reposicionamiento de accesibilidad vertical para las apps con formato de buzón en el modo de ventanas de pantalla completa.

Caso de uso o contexto
Reposiciona una app en horizontal en la parte superior o inferior para facilitar el acceso.
config_letterboxVerticalPositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Descripción
Configura la posición vertical del centro de la ventana de la app en formato letterbox.
El valor 0 corresponde al lado superior de la pantalla, y 1 corresponde al lado inferior.
Si el valor proporcionado es menor que 0 o mayor que 1, se ignora. Para el modo que no es de mesa, se usa la posición central (0.5). Para la posición de mesa, se usa la posición superior (0.0).

Caso de uso o contexto
Configurado en el centro en dispositivos con pantalla grande para una app en formato letterbox horizontal.
config_letterboxIsAutomaticReachabilityInBookModeEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si el posicionamiento automático de alcance horizontal en la postura de libro está habilitado para las apps en formato letterbox en el modo de ventanas de pantalla completa.

Caso de uso o contexto
Permite que una app en formato letterbox vertical se mueva entre la izquierda y la derecha cuando un dispositivo plegable está en postura de libro.
config_letterboxBookModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Descripción
Configura la posición horizontal del centro de la ventana de la app con formato de buzón cuando está en posición de libro.
0 corresponde al lado izquierdo de la pantalla y 1 al lado derecho. Si el valor proporcionado es menor que 0 o mayor que 1, se ignora y se usa la posición izquierda (0.0).

Caso de uso o contexto
Es un multiplicador de cuánto se mueve la posición de la app cuando se reposiciona en la postura de libro.
config_letterboxDefaultPositionForBookModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
Descripción
Configura la posición horizontal predeterminada de la ventana de la app en formato letterbox cuando la accesibilidad con una mano está habilitada y una app está en pantalla completa en orientación horizontal del dispositivo y en posición de libro. Cuando la accesibilidad está habilitada, la posición puede cambiar entre izquierda, centro y derecha:
  • Opción 0: izquierda
  • Opción 1: Centro
  • Opción 2: Derecha
Si el valor proporcionado está fuera de este rango, se supone que se eligió la opción 0 (izquierda).

Caso de uso o contexto
Es la posición predeterminada en la que se coloca la app en el modo de libro.
config_letterboxTabletopModePositionMultiplier frameworks/base/core/res/res/values/config.xml Float 0.0
Descripción
Configura la posición vertical del centro de la ventana de la app en formato de buzón cuando está en posición de mesa.
El valor 0 corresponde al lado superior de la pantalla, y 1 corresponde al lado inferior. Si el valor proporcionado es menor que 0 o mayor que 1, se ignora y se usa la posición superior 0.0.

Caso de uso o contexto
Es un multiplicador que indica cuánto se mueve la posición de la app en un dispositivo plegable cuando está en posición de mesa.
config_letterboxDefaultPositionForTabletopModeReachability frameworks/base/core/res/res/values/config.xml Integer 0
Descripción
Configura la posición vertical predeterminada de la ventana de la app en formato letterbox cuando la accesibilidad está habilitada y una app está en pantalla completa en la orientación vertical del dispositivo y en la posición de mesa. Cuando la accesibilidad está habilitada, la posición puede cambiar entre la parte superior, el centro y la parte inferior. Esta configuración define la predeterminada:
  • Opción 0: Parte superior
  • Opción 1: Centro
  • Opción 2: Parte inferior
Si el valor proporcionado está fuera de este rango, se supone que se eligió la opción 0 (superior).

Caso de uso o contexto
Posición predeterminada en la que se coloca la app en el modo de mesa.

Configuración

En esta sección, se enumeran todos los parámetros de configuración para personalizar y habilitar la configuración de relación de aspecto del usuario en Configuración > Apps > Relación de aspecto.

Name Ubicación Tipo Predeterminado
config_appCompatUserAppAspectRatioSettingsIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si se habilitan los parámetros de configuración de anulación de la relación de aspecto por usuario y por app.

Caso de uso o contexto
Habilita la función de parámetros de configuración de relación de aspecto en Configuración > Apps > Relación de aspecto.
config_appCompatUserAppAspectRatioFullscreenIsEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si la opción de anulación de pantalla completa por app está habilitada en la configuración de relación de aspecto del usuario.

Caso de uso o contexto
Habilita la opción Pantalla completa en la función de configuración de relación de aspecto del usuario.
Este parámetro de configuración ignora las restricciones de cambio de tamaño, relación de aspecto y orientación de una app.
config_userAspectRatioOverrideEntries packages/apps/Settings/res/values/config.xml string-array Todas las opciones están habilitadas de forma predeterminada.
Descripción
Configura la pantalla de configuración de la relación de aspecto de la app y las opciones de anulación de la relación de aspecto del usuario. Debe tener la misma longitud y el mismo orden que config_userAspectRatioOverrideValues.
Si se cambia, también se debe actualizar la lógica de copia de seguridad y restablecimiento para elegir el valor más cercano en UserAspectRatioBackupManager.java.

Caso de uso o contexto
Asignaciones para las cadenas que se muestran en Configuración.
config_userAspectRatioOverrideValues packages/apps/Settings/res/values/config.xml integer-array De forma predeterminada, se usan todos los strings del AOSP.
Descripción
Configura la pantalla de configuración de la relación de aspecto de la app y las opciones de anulación de la relación de aspecto del usuario. Debe tener la misma longitud y el mismo orden que config_userAspectRatioOverrideEntries. Los valores deben corresponder a PackageManager.UserMinAspectRatio.
Si se cambia, también se debe actualizar la lógica de Copia de seguridad y restablecimiento para elegir el valor más cercano en UserAspectRatioBackupManager.java.

Caso de uso o contexto
Asignaciones para las opciones del backend PackageManager.UserMinAspectRatio:
  • Predeterminado de la app: 0
  • Pantalla dividida: 1
  • Relación de aspecto de la pantalla: 2
  • 4:3: 3
  • 16:9: 4
  • 3:2: 5
  • Pantalla completa: 6
Recursos de diseño estáticos con tema claro packages/apps/Settings/res/drawable/ic_app_aspect_ratio_<option>.xml vector Recursos horizontales para pantallas plegables
Descripción
Configura los elementos de diseño disponibles:


Caso de uso o contexto
Imágenes estáticas con tema claro debajo de cada opción en Configuración > Información de la app > Relación de aspecto.
Recursos de diseño estáticos con tema oscuro packages/apps/Settings/res/drawable-night/ic_app_aspect_ratio_<option>.xml vector Recursos horizontales para pantallas plegables
Descripción
Configura los elementos de diseño disponibles:


Caso de uso o contexto
Imágenes estáticas con tema oscuro en cada opción de Configuración > Información de la app > Relación de aspecto.
Drawable dinámico
user_aspect_ratio_education.json		 packages/apps/Settings/res/raw/user_aspect_ratio_education.json JSON Recurso dinámico horizontal para dispositivos plegables
Descripción
Configura una ilustración de Lottie en UserAspectRatioAppsPageProvider.

Caso de uso o contexto
Una animación en la lista de apps: Configuración > Apps > Relación de aspecto.

Educación

En esta sección, se enumeran todos los parámetros de configuración para informar a los usuarios sobre las funciones de compatibilidad de apps.

Name Ubicación Tipo Predeterminado
config_letterboxIsEducationEnabled frameworks/base/core/res/res/values/config.xml Bool false
Descripción
Configura si se habilita la orientación sobre el formato letterbox para las apps en pantalla completa con formato letterbox.

Caso de uso o contexto
Consulta la figura 1 para ver un caso de uso de la orientación sobre el formato letterbox para las apps en pantalla completa.
config_letterboxIsRestartDialogEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
Descripción
Configura si el diálogo de reinicio extendido está habilitado.

Caso de uso o contexto
Consulta la figura 2 para ver un caso de uso del diálogo de reinicio extendido.
config_letterboxIsReachabilityEducationEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool false
Descripción
Configura si se habilita información adicional sobre la accesibilidad.

Caso de uso o contexto
Consulta la figura 3 para ver un caso de uso de la información sobre la accesibilidad.
config_isSizeCompatRestartButtonEnabled frameworks/base/libs/WindowManager/Shell/res/values/config.xml Bool true
Descripción
Configura si el botón de reinicio de compatibilidad de tamaño está habilitado.

Caso de uso o contexto
Un botón de reinicio para reiniciar la configuración de apps que no pueden cambiar de tamaño después de que cambia el tamaño de la ventana, por ejemplo, cuando se ingresa a pantalla dividida o se rota la pantalla.
Consulta la figura 4 para ver un caso de uso del botón de reinicio de compatibilidad de tamaño.
config_letterboxRestartButtonHideTolerance frameworks/base/libs/WindowManager/Shell/res/values/config.xml Integer 100
Descripción
Configura la tolerancia mínima del porcentaje de límites de actividad dentro de su tarea para ocultar el botón de reinicio de compatibilidad de tamaño. Se ignoran los valores inferiores a 0 o superiores a 100.
100 es el valor predeterminado en el que la actividad debe ajustarse exactamente dentro de la tarea para permitir que se oculte el botón de reinicio de compatibilidad de tamaño. El valor 0 significa que el botón de reinicio de compatibilidad de tamaño siempre está oculto.

Caso de uso o contexto
Se usa en dispositivos casi cuadrados para ocultar el botón de reinicio cuando el usuario rota las apps que no se pueden cambiar de tamaño, pero reiniciar la app no mejorará drásticamente la IU.

En las siguientes imágenes, se muestran casos de uso de la capa superpuesta de educación:

Educación sobre el letterboxing para apps en pantalla completa

Figura 1: Educación sobre el letterboxing para apps en pantalla completa

Ejemplo de un diálogo de reinicio extendido.

Figura 2: Diálogo de reinicio extendido

Ejemplo de educación sobre accesibilidad.

Figura 3: Educación sobre accesibilidad

Un ejemplo del botón de reinicio de compatibilidad de tamaño.

Figura 4: Botón de reinicio del modo de compatibilidad de tamaño