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.
| Nombre | Ubicación | Tipo | Predeterminado |
|---|---|---|---|
ignoreOrientationRequest |
display_settings.xml |
config | falsetrue para pantallas grandes (mayor o igual a 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 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.
| Nombre | 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 vertical en forma de barra de caramelo. |
|||
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.
| Nombre | 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 la 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 un letterbox 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 tiempo de compilación: PRODUCT_PROPERTY_OVERRIDES += camera.enable_landscape_to_portrait=trueEste 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. |
|||
config_isCameraCompatSimulateRequestedOrientationTreatmentEnabled |
frameworks/base/core/res/res/values/config.xml |
Bool |
true |
| Descripción Indica si está habilitado el tratamiento de compatibilidad con la cámara, que simula la orientación solicitada de una app. El propósito del tratamiento es mitigar los problemas causados por una discrepancia de orientación entre el búfer de la cámara y la ventana de la app. Esto incluye el letterboxing de actividades de orientación fija conectadas a la cámara, el recorte del búfer de la cámara (rotar y recortar) y el aislamiento de la rotación de la pantalla para que coincida con la orientación esperada de la app. Caso de uso o contexto Simular la orientación solicitada para las actividades de la cámara en:
En Android 17 y versiones posteriores, este parámetro de configuración inhabilita el tratamiento de rotación forzada de config_isWindowManagerCameraCompatTreatmentEnabled y unifica las políticas para el aislamiento de la rotación de pantalla, el formato letterbox y la rotación y el recorte de la cámara para las apps de cámara con orientación fija. |
|||
config_isCameraCompatSimReqOrientationLandscapeTreatmentEnabled |
frameworks/base/core/res/res/values/config.xml |
Bool |
false |
| Descripción Indica si el tratamiento de compatibilidad de la cámara que simula la orientación solicitada de una app está habilitado para las cámaras horizontales. El propósito del tratamiento es mitigar los problemas causados por las apps que codifican de forma rígida los sensores de la cámara vertical. El tratamiento incluye el letterboxing de actividades de orientación fija conectadas a la cámara, el recorte del búfer de la cámara (rotar y recortar), la orientación del sensor en vertical y el aislamiento de la rotación de la pantalla para que coincida con la orientación esperada de la app. Caso de uso o contexto En Android 17 y versiones posteriores, este tratamiento es el mismo que el tratamiento de simulación de la orientación solicitada para config_isCameraCompatSimulateRequestedOrientationTreatmentEnabled, pero para dispositivos con cámaras orientadas en horizontal. |
|||
IU y fondo
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.
| Nombre | 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 a 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:
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 AOSP no se encargará de los errores. |
|||
config_letterboxBackgroundColor |
frameworks/base/core/res/res/values/config.xml |
Color |
@color/system_neutral1_1000 |
| Descripción Configura el color del fondo de la banda negra si se cumple una de las siguientes condiciones true:
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 AOSP no se encargará de los errores. |
|||
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 AOSP no se encargará de los errores. |
|||
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 AOSP no se encargará de los errores. |
|||
config_enableSelfKillRecoveryBetweenInternalDisplays |
frameworks/base/core/res/res/values/config.xml |
Bool |
false |
| Descripción Cuando es true,
los movimientos de pantalla entre pantallas internas no están exentos de la
lógica de recuperación de autodestrucción.Caso de uso o contexto En Android 17 y versiones posteriores, el proceso de recuperación de autodestrucción solo se habilita para los movimientos de pantalla que involucran monitores externos. Sin embargo, el proceso también es eficaz en dispositivos plegables con diferentes densidades en sus pantallas interior y exterior. Esta configuración habilita el proceso para esos dispositivos. |
|||
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.
| Nombre | 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). Para la postura del libro, se usa la posición izquierda (0.0).Caso de uso o contexto De forma predeterminada, se centra en una app en formato vertical con bandas laterales. |
|||
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 posición 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 posición 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 inferior a 0 o superior a 1, se ignora y se usa la posición izquierda (0.0).Caso de uso o contexto Es un multiplicador que indica cuánto se mueve la posición de la app cuando se la 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 con una mano está habilitada, la posición puede cambiar entre izquierda, centro y derecha:
0 (izquierda).Caso de uso o contexto 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 letterbox 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 Multiplicador de 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 con una mano 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:
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.
| Nombre | 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 app del usuario. 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:
|
|||
| Recursos de diseño estáticos con tema claro | packages/apps/Settings/res/drawable/ic_app_aspect_ratio_<option>.xml |
vector |
Recursos horizontales para dispositivos 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 dispositivos 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ámicouser_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.
| Nombre | Ubicación | Tipo | Predeterminado |
|---|---|---|---|
config_letterboxIsEducationEnabled |
frameworks/base/core/res/res/values/config.xml |
Bool |
false |
| Descripción Configura si se habilita la educació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 educació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 educativa:
Figura 1: Educación sobre el letterboxing para apps en pantalla completa
Figura 2: Diálogo de reinicio extendido
Figura 3: Educación sobre accesibilidad
Figura 4: Botón de reinicio de compatibilidad de tamaño