Modo de compatibilidad del dispositivo

Android activa un modo de compatibilidad para las apps que declaran restricciones de orientación o cambio de tamaño. El modo de compatibilidad garantiza un comportamiento aceptable de la app en dispositivos con pantalla grande y teléfonos con tapa plegable, pero con una usabilidad deficiente.

Las anulaciones por app permiten que los fabricantes de dispositivos cambien el comportamiento de la app para mejorar la experiencia del usuario o evitar que las apps fallen en dispositivos específicos.

Dispositivos de referencia

Los siguientes dispositivos pueden requerir anulaciones por app debido a configuraciones inusuales o no compatibles con las apps:

• Tablets: La orientación natural de algunas tablets, como la Pixel Tablet, es horizontal. Un dispositivo se encuentra en su orientación natural cuando Display#getRotation() muestra Surface.ROTATION_0. Si las apps suponen que ROTATION_0 es vertical, es posible que los diseños de la app y la vista previa de la cámara no coincidan con la pantalla del dispositivo.
• Plegables horizontales: Algunos dispositivos plegables, como el Pixel Fold, están en orientación vertical cuando están plegados, pero en orientación horizontal cuando están desplegados. Si las apps suponen que la orientación desplegada es vertical, es probable que haya bucles parpadeantes o problemas de diseño.
• Teléfonos plegables con tapa: Estos teléfonos suelen tener orientación vertical. Sin embargo, cuando se pliegan, los teléfonos suelen tener una pantalla pequeña en orientación horizontal. Las apps deben identificar y adaptarse a las diferentes orientaciones de las pantallas.

Problemas comunes de compatibilidad

Las apps experimentan problemas de compatibilidad con mayor frecuencia debido a restricciones en la orientación de la app, la capacidad de cambiar el tamaño y la relación de aspecto, el manejo incorrecto de la orientación de la vista previa de la cámara y las APIs que se usan de manera inadecuada.

Formato letterbox

El formato letterbox posiciona la app en el centro de la pantalla o, en pantallas grandes, a un lado o al otro para facilitar el acceso. Los elementos mate (barras de colores sólidos o fondos de pantalla desenfocados) ocupan el área de visualización sin usar a los costados o en las partes inferior y superior de la app.

El formato letterbox suele utilizarse en dispositivos con pantallas grandes, ya que las dimensiones y la relación de aspecto de la pantalla suelen ser diferentes de las de los teléfonos estándar, para los que se diseñan la mayoría de las apps.

Figura 1: La app solo con orientación vertical tiene formato letterbox cuando la tablet o el dispositivo plegable está en posición horizontal.

Problema

La app no admite todas las configuraciones de pantalla porque tiene una orientación o relación de aspecto fijas, o no puede cambiar de tamaño.

Entre los parámetros de configuración que controlan la orientación y el ajuste de tamaño de la app, se incluyen los siguientes:

• screenOrientation: Especifica una orientación fija para una app. Las apps también pueden establecer la orientación en el tiempo de ejecución mediante Activity#setRequestedOrientation().

• resizeableActivity: Indica si el sistema puede cambiar el tamaño de las apps para que se ajusten a ventanas de diferentes dimensiones. En Android 11 (nivel de API 30) y versiones anteriores, especifica si las apps admiten el modo multiventana. En Android 12 (nivel de API 31) y versiones posteriores, especifica si las apps admiten el modo multiventana en pantallas pequeñas (ancho mínimo < 600 dp). En Android 12 y versiones posteriores, las apps admiten el modo multiventana en pantallas grandes (ancho mínimo >= 600 dp), independientemente de esta configuración.

• maxAspectRatio: Especifica la relación de aspecto máxima que admite la app. Solo las apps con resizeableActivity establecido en false pueden configurar maxAspectRatio.

• minAspectRatio: Especifica la relación de aspecto mínima que admite la app. Solo las apps con resizeableActivity establecido en false pueden configurar minAspectRatio.

cancel

La app con solo orientación vertical no se puede usar en dispositivos en posición horizontal

Optimización

La app debe admitir todas las orientaciones y tamaños de pantallas y dispositivos en modo multiventana. Quita todas las restricciones de orientación y relación de aspecto fijas de los diseños de tu app y del archivo de manifiesto de la app.

check_circle

La app admite todas las orientaciones del dispositivo

Solución al problema de compatibilidad

Si una app con orientación o relación de aspecto fijas se ejecuta en una ventana en la que no es compatible directamente con el tamaño o la orientación de la ventana, Android aplica el formato letterbox para preservar la continuidad.

A partir de Android 12 (nivel de API 31) y hasta la versión 12L (nivel de API 32), la plataforma aplica una variedad de mejoras a las apps en formato letterbox. Los fabricantes de dispositivos implementan las mejoras de la IU. No necesitas realizar ningún desarrollo adicional para que tu app se beneficie de las mejoras.

Android 12 (nivel de API 31) incluye las siguientes mejoras estéticas que los fabricantes de dispositivos pueden configurar:

• Esquinas redondeadas: Las esquinas de la ventana de la app lucen un aspecto más refinado.
• Transparencia de la barra del sistema: Las barras de estado y navegación, que se superponen a la app, son semitransparentes, lo que hace que los íconos de las barras siempre sean visibles sobre el fondo del formato letterbox.
• Relación de aspecto configurable: La relación de aspecto de la app se puede ajustar para mejorar su aspecto.

Figura 2: App en formato letterbox con mejoras en la IU.

La versión 12L (nivel de API 32) agrega las siguientes mejoras funcionales:

• Posicionamiento configurable: En pantallas grandes, los fabricantes de dispositivos pueden posicionar la app en el lado izquierdo o derecho de la pantalla, lo que facilita la interacción.

• Botón Reiniciar rediseñado: Los fabricantes de dispositivos pueden darle un nuevo aspecto al botón Reiniciar para el modo de compatibilidad de tamaño con el fin de que los usuarios lo reconozcan mejor.

Android 13 (nivel de API 33) agrega un diálogo de información para el usuario sobre cómo posicionar la app en formato letterbox en la pantalla o incluir el formato letterbox en el modo de pantalla dividida:

Figura 3: App en formato letterbox con un diálogo de información para el usuario.

Modo de compatibilidad de tamaño

El modo de compatibilidad de tamaño es el formato letterbox que incluye un control de reinicio. El control permite a los usuarios reiniciar la app y volver a dibujar la pantalla. Android invoca el modo de compatibilidad de tamaño para apps que se determina que no pueden cambiar de tamaño. Cuando una actividad se traslada a un contenedor de pantalla que no es compatible con sus dimensiones, el sistema puede cambiar la escala de la app para incluir al menos una dimensión en la pantalla del dispositivo.

Entre los cambios de configuración del dispositivo que pueden activar el modo de compatibilidad de tamaño, se incluyen los siguientes:

• Rotación del dispositivo
• Plegar o desplegar un dispositivo plegable
• Cambiar entre los modos de visualización de pantalla completa y pantalla dividida

Problema

Por lo general, el modo de compatibilidad de tamaño se aplica a actividades que tienen restricciones de orientación o relación de aspecto y que están configuradas (o determinadas por el sistema) para que no puedan cambiar de tamaño.

Se considera que tu app puede cambiar de tamaño y que no se colocará en el modo de compatibilidad de tamaño si cumple con alguno de los siguientes criterios:

• Se puede cambiar el tamaño con resizeableActivity="true".
• Admite el modo pantalla en pantalla (PIP).
• Está incorporada.
• Tiene la anulación por app de FORCE_RESIZE_APP aplicada por el fabricante del dispositivo (se ignoran las propiedades que estableció la app).

Si tu app no cumple con ninguna de las condiciones, se considera que no puede cambiar de tamaño y se puede establecer en modo de compatibilidad de tamaño.

cancel

La app que no puede cambiar de tamaño falla en el modo multiventana

Optimización

La app debe admitir todos los tamaños de visualización. Para que tu app pueda cambiar de tamaño, configura el atributo android:resizeableActivity del elemento <activity> o <application> en true en el manifiesto de la app. Crea diseños responsivos o adaptables para tu app. Para obtener más información, consulta Cómo brindar compatibilidad con diferentes tamaños de pantalla y Compatibilidad con el modo multiventana.

check_circle

La app funciona en todos los tamaños de ventana

Solución al problema de compatibilidad

Android coloca una app en el modo de compatibilidad de tamaño cuando el sistema determina que se puede mejorar la visualización de la app en formato letterbox si se cambia su escala para que ocupe toda la ventana de la pantalla en al menos una dimensión. El sistema muestra un control de reinicio que vuelve a crear el proceso de la app, la actividad y el dibujo de la pantalla. Consulta también la Descripción general de los procesos y subprocesos.

warning

Se agrega formato letterbox en orientación horizontal a la app solo con modo vertical; el control de reinicio modifica la escala

Bucles parpadeantes

Si una app no admite todas las orientaciones de pantalla, puede solicitar de manera reiterada orientaciones nuevas cuando se produce un cambio de configuración, lo que crea un bucle infinito que hace que la pantalla parpadee o que la app rote sin fin.

Problema

En Android 12 (nivel de API 31) y versiones posteriores, los fabricantes de dispositivos pueden configurar sus dispositivos para ignorar las restricciones de orientación que especifican las apps y, en su lugar, usar las restricciones para aplicar los modos de compatibilidad. Por ejemplo, un dispositivo plegable podría ignorar la configuración android:screenOrientation="portrait" de una actividad cuando esta se muestra en la pantalla interior en tamaño tablet en orientación horizontal del dispositivo.

Si se ignoran las restricciones de orientación de una app, esta podrá establecer su orientación de manera programática llamando a Activity#setRequestedOrientation(). La llamada activa el reinicio de una app si esta no controla los cambios de configuración (consulta Administra los cambios en la configuración). Después del reinicio, las restricciones de orientación de la app se vuelven a ignorar, la app repite la llamada a setRequestedOrientation(), la llamada activa un reinicio de la app, y así sucesivamente, en un bucle automático.

Otra forma en la que puedes encontrar esto es cuando la orientación natural (la orientación habitual que determina Android) de la pantalla de un dispositivo es horizontal (es decir, cuando se llama a Display#getRotation() se muestra Surface.ROTATION_0 mientras el dispositivo tiene una relación de aspecto horizontal). Históricamente, las apps suponen que Display.getRotation() = Surface.ROTATION_0 significa que el dispositivo se encuentra en orientación vertical, pero no siempre es así, por ejemplo, en la pantalla interna de algunos dispositivos plegables y en algunas tablets.

Una app con orientación horizontal en una pantalla interior plegable puede verificar la rotación de la pantalla, recibir un valor de ROTATION_0, suponer que la orientación natural del dispositivo es vertical y llamar a setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT ) para volver a configurar el diseño de la app. Después de que se reinicia la app (en orientación horizontal), es posible que vuelva a verificar la rotación de la pantalla, reciba un valor de ROTATION_0, llame a setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT) y continúe el bucle infinito.

cancel

La app solo con modo horizontal en la pantalla vertical realiza llamadas repetidas a Activity#setRequestedOrientation()

Optimización

Las apps no deben hacer lo siguiente:

• Establece una orientación predeterminada con Activity#setRequestedOrientation() en el método onCreate() de la actividad, ya que la solicitud de orientación puede activarse de forma inesperada por cambios de configuración no controlados.
• Dar por sentado que la orientación natural del dispositivo (ROTATION_0) es vertical
• Establece la orientación en función de indicadores no relacionados con el tamaño actual de la ventana, como Display#getRotation(), la presencia de FoldingFeature o las APIs obsoletas.

check_circle

La app controla los cambios de configuración, no tiene restricciones de orientación, por lo que no entra a un bucle parpadeante

Solución al problema de compatibilidad

Android ignora las llamadas a Activity#setRequestedOrientation() en las siguientes situaciones:

• Ya se reinició la actividad a partir de una llamada anterior al método o se habilitó el tratamiento de rotación de compatibilidad forzada con la cámara (consulta Vista previa de la cámara a continuación).

  Los fabricantes de dispositivos pueden aplicar este comportamiento a una app con OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION.

• La actividad realizó más de dos solicitudes de orientación en un segundo, lo que indica que se produjo un bucle. De las dos solicitudes en el bucle, Android usa la que maximiza el área de visualización de la app.

  Los fabricantes de dispositivos pueden aplicar este comportamiento a una app con OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED.

Vista previa de cámara

La vista previa (o el visor) de la cámara de las apps de cámara puede desalinearse o distorsionarse en tablets, laptops y pantallas plegables.

Problema

En el Documento de definición de compatibilidad de Android, se indica que un sensor de imagen de la cámara "SE DEBE orientar para que la dimensión larga de la cámara se alinee con la dimensión larga de la pantalla".

A menudo, las apps suponen que la orientación del dispositivo y el sensor de la cámara son verticales, una suposición razonable en los teléfonos celulares estándar. Sin embargo, la orientación natural de las tablets, las laptops y los sensores de la cámara puede ser horizontal. Además, los nuevos factores de forma, como los dispositivos plegables, pueden tener varias orientaciones naturales y varios sensores de la cámara en diferentes orientaciones.

Iniciar una actividad con una orientación de cámara que la app no espera o cambiar entre diferentes cámaras o pantallas de dispositivos (en dispositivos plegables) puede generar una vista previa de la cámara desalineada o distorsionada.

cancel

Vista previa de la cámara desalineada y distorsionada en un plegable de pantalla grande

Optimización

Las apps de cámara deben identificar y administrar correctamente la orientación del dispositivo y del sensor de la cámara para mostrar una vista previa de la cámara alineada y ajustada de manera adecuada. Las apps deben calcular la rotación del dispositivo y del sensor, y la relación de aspecto de la pantalla o la ventana, y, luego, aplicar los resultados a la vista previa de la cámara. Para obtener orientación detallada, consulta Vista previa de la cámara y Presentación del visor de la cámara.

check_circle

La vista previa de la cámara está alineada y ajustada correctamente en todas las orientaciones del dispositivo

Solución al problema de compatibilidad

Un dispositivo se encuentra en orientación natural cuando Display#getRotation() muestra Surface.ROTATION_0. El sistema calcula CameraCharacteristics.SENSOR_ORIENTATION a partir de la orientación natural del dispositivo. Android alinea la ventana vertical de las apps con restricción vertical con la orientación natural del dispositivo, que es lo que espera la mayoría de las apps. Android también recorta la imagen del sensor de la cámara cuando la orientación del sensor es horizontal y la vista previa de la cámara es vertical. Las soluciones específicas incluyen las siguientes:

• Fuerza la vista previa de rotación de la cámara en apps con restricción vertical: Las apps restringidas a orientación vertical esperan que la orientación natural del dispositivo y la del sensor de la cámara sean verticales. Sin embargo, en Android 12 (nivel de API 31) y versiones posteriores, las apps pueden ejecutarse en varias orientaciones si los fabricantes ignoran la especificación de orientación.

  Cuando se conecta una app con restricción vertical a la cámara, Android rota de manera forzosa la app para alinear la ventana vertical de la app con la orientación natural del dispositivo.

  En algunas tablets (consulta los dispositivos de referencia), la ventana vertical de la app se rota a la pantalla completa vertical para alinearse con la orientación natural del dispositivo. La app ocupa la pantalla completa después de forzar la rotación.

  

  warning

  Tablet: Fuerza la rotación de la app solo con orientación vertical.

  En la pantalla interior horizontal de los dispositivos plegables (consulta los dispositivos de referencia), las actividades solo verticales se rotan al modo horizontal para alinearse con la orientación natural desplegada. La app tiene formato letterbox después de forzar la rotación.

  

  warning

  Plegable: Fuerza la rotación de la app con restricción vertical. La app también tiene formato letterbox.

• Recorte del interior de la cámara frontal: El sensor interior de la cámara frontal en algunos dispositivos plegables se encuentra en orientación horizontal. Además de forzar la rotación de la vista previa de la cámara en la pantalla interior plegable, Android recorta el campo visual interno de la cámara frontal (horizontal) para que el sensor capture una vista opuesta a la orientación del dispositivo.

• Forzar la actualización de vistas previas de la cámara: El sistema alterna los métodos de actividad onStop() y onStart() (de forma predeterminada) o onPause() y onResume() (aplicado por la anulación por app OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE) después de forzar la rotación para garantizar que la vista previa de la cámara se muestre correctamente.

• Ajuste de relación de aspecto: El sistema cambia de forma dinámica la relación de aspecto de la vista previa de la cámara rotada de manera forzosa a una relación de aspecto mínima más alta, lo que garantiza que se ajuste correctamente la vista previa de la cámara.

Los desarrolladores de apps pueden anular estas soluciones alternativas si las apps controlan la vista previa de la cámara correctamente. Consulta Anulaciones por app.

APIs que suelen usarse de manera inadecuada

Como Android agregó compatibilidad con funciones como el modo multiventana y dispositivos, como los plegables, las APIs heredadas dejaron de estar disponibles y se reemplazaron por APIs actualizadas que funcionan con todos los tamaños de pantalla y factores de forma de dispositivos. Sin embargo, las APIs obsoletas aún están disponibles para brindar retrocompatibilidad.

Algunas APIs de View se diseñaron con fines especiales que los desarrolladores no siempre comprenden bien.

Problema

Los desarrolladores siguen usando las APIs de Display obsoletas y suponen incorrectamente que las APIs devuelven los límites de la app en lugar de los límites del área de visualización del dispositivo. O bien, usan erróneamente APIs de vistas con propósitos especiales para obtener métricas de visualización generales. El resultado son errores de cálculo cuando se reposicionan los elementos de la IU después de los eventos de cambio de tamaño de la ventana de la app, lo que causa problemas de diseño.

APIs de Display obsoletas y que suelen usarse de manera inadecuada:

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

Para obtener más información, consulta Compatibilidad con el modo multiventana.

APIs de View que se usan de manera inadecuada:

• getWindowVisibleDisplayFrame()
• getLocationOnScreen()

cancel

La API obsoleta calcula erróneamente los límites de la app. El contenido de la app desaparece de la pantalla.

Optimización

Nunca dependas del tamaño de la pantalla física para posicionar elementos de la IU. Migra tu app a las APIs en función de WindowMetrics, incluidas las siguientes APIs de WindowManager:

• Plataforma:

  • getCurrentWindowMetrics()
  • getMaximumWindowMetrics()

• Jetpack:

  • WindowMetricsCalculator#computeCurrentWindowMetrics()

  • WindowMetricsCalculator#computeMaximumWindowMetrics()

check_circle

La API calcula correctamente las métricas de la ventana de la app

Solución al problema de compatibilidad

Dos anulaciones ajustan las APIs de Display obsoletas y las APIs de View que se usan de manera inadecuada para mostrar los límites de la app: ALWAYS_SANDBOX_DISPLAY_APIS para las APIs de Display; OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS para las APIs de View. ALWAYS_SANDBOX_DISPLAY_APIS también se aplica de forma predeterminada a las apps que califican para el modo de compatibilidad de tamaño.

Actividades transparentes

Las actividades transparentes son el resultado de estilos de fondo transparentes, por ejemplo:

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

Los temas relacionados con los diálogos, como Theme.MaterialComponents.Dialog, pueden incluir estilos que hacen que las actividades sean transparentes.

Las actividades transparentes no cubren todo el espacio de visualización disponible, lo que dificulta su administración porque el área de visualización disponible puede cambiar en función de cambios de configuración, como la rotación del dispositivo, el plegado y desplegado del dispositivo, y el modo multiventana.

Problema

Una actividad transparente debe cumplir con los límites de la primera actividad opaca debajo de la actividad transparente en la pila de actividades de tareas. Sin embargo, una actividad opaca que inicia un diálogo de permisos puede ser un trampolín (una actividad que inicia otra actividad y luego desaparece); por lo tanto, el sistema no puede determinar los límites de la actividad disparadora que inició la actividad del diálogo de permiso transparente.

cancel

El diálogo está mal posicionado porque la actividad se inició desde un trampolín

Optimización

Las actividades transparentes heredan sus restricciones de la actividad opaca superior que se encuentra debajo de ellas en la pila de actividades de una tarea. La actividad opaca debe estar disponible durante todo el ciclo de vida de la actividad transparente, desde la creación de la actividad hasta la destrucción. Por este motivo, no inicies solicitudes de permisos desde actividades disparadoras.

Si una actividad disparadora inicia una solicitud de permiso, es posible que el usuario no pueda ver el diálogo correspondiente porque la actividad disparadora se destruyó antes de que el usuario haya tenido la oportunidad de responder al diálogo y es posible que las dimensiones y la posición de la actividad del diálogo se hayan calculado de forma incorrecta.

Las apps siempre deben iniciar solicitudes de permisos desde actividades que permanecen visibles hasta que el usuario toma una decisión respecto del permiso.

Esquinas redondeadas

Una actividad puede ser transparente debido a un estilo que especifica la transparencia en segundo plano o porque el contenido de la actividad no ocupa el espacio de visualización disponible. Si una actividad transparente ocupa el espacio de visualización disponible, el sistema aplica automáticamente esquinas redondeadas a la actividad cuando el fabricante del dispositivo lo configura para que lo haga. Sin embargo, si una actividad transparente (como un diálogo de permisos) no ocupa el espacio disponible, podrás decidir si aplicar esquinas redondeadas o no.

Los diálogos de permiso no ocupan el espacio de visualización disponible porque el diseño del diálogo generalmente usa LayoutParams.WRAP_CONTENT en lugar de LayoutParams.MATCH_PARENT.

check_circle

Diálogo con esquinas redondeadas posicionadas correctamente sobre la actividad de inicio visible

Solución al problema de compatibilidad

Mantén visibles las actividades que inician actividades de diálogo hasta que el usuario lo haya respondido.

El sistema garantiza que una actividad transparente herede todas las restricciones de la primera actividad opaca debajo de la transparente en la pila, incluidas las restricciones relacionadas con lo siguiente:

• Modo de compatibilidad de tamaño
• Orientación
• Relación de aspecto

Juegos de Unity

Los juegos de Unity se ejecutan en modo multiventana o en pantalla completa en Android. Sin embargo, muchos juegos de Unity pierden el enfoque y dejan de dibujar contenido cuando la app se coloca en el modo multiventana.

Problema

Unity agregó una opción Resizable Window en Unity 2019.4 para admitir el modo multiventana en Android. Sin embargo, la implementación inicial no reaccionó correctamente al ciclo de vida de la actividad en el modo multiventana, lo que provocó que UnityPlayer suspendiera la reproducción cuando la app perdía el enfoque. El reproductor renderizó una pantalla negra o el último fotograma congelado del juego. El juego se reanudó solo cuando el usuario presionó la pantalla. Muchas apps que usan el motor de Unity tienen este problema y se renderizan como una ventana negra en el modo multiventana.

cancel

El juego pierde el foco en el modo multiventana y se renderiza como una ventana negra

Optimización

Actualiza Unity a la versión 2019.4.40 o una posterior y vuelve a exportar el juego. Mantén marcada la opción Resizable Window en la configuración del reproductor de Android; de lo contrario, el juego se detendrá cuando no esté en primer plano, aunque sea completamente visible en el modo multiventana.

check_circle

El juego procesa el contenido correctamente en el modo multiventana, incluso cuando no está en foco.

Solución al problema de compatibilidad

Los fabricantes de dispositivos pueden aplicar la anulación por app OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS para proporcionar un evento de enfoque falso a una app en el modo multiventana. La anulación permite que la actividad vuelva a dibujar el contenido y no se oscurezca.

Prueba tu app para detectar problemas de compatibilidad

Para probar tu app y comprender cómo se comporta en diferentes factores de forma, aprovecha los siguientes recursos:

• Transmisión de dispositivos: Para probar tu app en dispositivos de producción (incluidos los dispositivos de referencia) alojados en centros de datos de Google, consulta Transmisión de dispositivos Android, con la tecnología de Firebase .
• Emuladores en Android Studio Hedgehog: Si quieres obtener información para crear emuladores para dispositivos de referencia, consulta Cómo crear y administrar dispositivos virtuales.
• Emulador de Android Studio al que se le puede cambiar el tamaño: Si quieres obtener información para acceder a dispositivos virtuales, consulta Cómo ejecutar apps en Android Emulator.

Formato letterbox

Verifica que cada actividad pueda usar todo el espacio de visualización disponible para la app. Primero, declara el siguiente código en tu carpeta de prueba:

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

Luego, ejecuta una prueba para confirmar el comportamiento y asegurarte de que la actividad objetivo no esté en formato 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();
        });
    }
}

Lo ideal es que ejecutes este tipo de prueba solo hasta que se complete y confirme que las actividades de tu app ocupan todo el espacio de visualización disponible para ella. Prueba tu app en todos los tipos de dispositivos para garantizar un comportamiento coherente.

Anulaciones por app

Android proporciona anulaciones que cambian el comportamiento configurado de las apps. Por ejemplo, la anulación de FORCE_RESIZE_APP le indica al sistema que omita el modo de compatibilidad de tamaño y cambie el tamaño de la app para que se adapte a las dimensiones de la pantalla, incluso si resizeableActivity="false" está especificado en el manifiesto de la app.

Los fabricantes de dispositivos aplican anulaciones para determinadas apps (o todas las apps) en dispositivos específicos con pantalla grande. En Android 14 (nivel de API 34) y versiones posteriores, los usuarios pueden aplicar anulaciones a las apps a través de la configuración del dispositivo.

Anulaciones por app de usuario

En Android 14 y versiones posteriores, un menú de configuración permite a los usuarios cambiar la relación de aspecto de las apps. Los dispositivos con pantalla grande, como los dispositivos de referencia, implementan el menú.

El menú contiene una lista de todas las apps instaladas en el dispositivo. Los usuarios eligen una app y, luego, la establecen en 3:4, 1:1, pantalla completa o algún otro valor configurado por el fabricante del dispositivo. Los usuarios también pueden restablecer la relación de aspecto al valor predeterminado de la app, que se especifica en el manifiesto de la app.

Para inhabilitar la anulación de compatibilidad, las apps pueden configurar las siguientes etiquetas PackageManager.Property:

• PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE

  Para inhabilitar la anulación de compatibilidad de la relación de aspecto del usuario, agrega la propiedad al manifiesto de la app y establece el valor en false:

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

  Tu app se excluirá de la lista de apps en la configuración del dispositivo. Los usuarios no podrán anular la relación de aspecto de la app.

  Establecer la propiedad en true no tiene ningún efecto.

• PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE

  Para inhabilitar la opción de pantalla completa de la anulación de compatibilidad de la relación de aspecto del usuario, agrega la propiedad al manifiesto de tu app y establece el valor en false:

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

  La opción de pantalla completa se quitó de la lista de opciones de relación de aspecto en la configuración del dispositivo. Los usuarios no podrán aplicar la anulación de pantalla completa a tu app.

  Establecer esta propiedad en true no tiene ningún efecto.

Optimiza tu app para todas las pantallas: No establezcas restricciones de relación de aspecto en tu app. Usa clases de tamaño de ventana para admitir diferentes diseños en función de la cantidad de espacio de visualización disponible.

Anulaciones por app del fabricante del dispositivo

Los fabricantes de dispositivos aplican anulaciones por app en dispositivos seleccionados. Los dispositivos de referencia pueden aplicar algunas de las anulaciones a una variedad de apps de forma predeterminada.

Las apps pueden inhabilitar la mayoría de las anulaciones (consulta la tabla Anulaciones por app a continuación).

Puedes probar la app con las anulaciones habilitadas o inhabilitadas usando el marco de compatibilidad (consulta Herramientas del marco de compatibilidad). Cuando se habilitan, las anulaciones se aplican a toda la app.

También puedes usar Android Debug Bridge (adb) para habilitar o inhabilitar anulaciones y determinar cuáles se aplican a tu app.

Habilita o inhabilita las anulaciones de la siguiente manera:

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

Para los dispositivos de referencia, verifica qué anulaciones se aplican a tu app:

adb shell dumpsys platform_compat | grep <package name>

En la siguiente tabla, se enumeran las anulaciones disponibles junto con la guía sobre cómo optimizar tu app para que no tenga que depender de las anulaciones. Puedes agregar marcas de propiedad al manifiesto de la app para inhabilitar algunas anulaciones.

FORCE_RESIZE_APP

Fuerza los paquetes a los que se aplica la anulación a que puedan cambiar el tamaño. No cambia si la app se puede poner en modo multiventana, pero permite que cambie el tamaño sin ingresar al modo de compatibilidad de tamaño cuando cambia el tamaño de la pantalla.

Cómo las apps pueden obtener el mismo resultado que la anulación

En el manifiesto de la app, establece el atributo android:resizeableActivity en true o, para admitir el cambio de tamaño mientras inhabilitas el modo multiventana con android:resizeableActivity=false, establece la marca de metadatos android.supports_size_changes en true.

Cómo optimizar apps

Usa diseños responsivos o adaptables para permitir que las apps se adapten a todos los tamaños de visualización y las relaciones de aspecto. Consulta Cómo brindar compatibilidad con diferentes tamaños de pantalla.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación y hacer que la app pueda cambiar de tamaño:

adb shell am compat enable FORCE_RESIZE_APP <package>

Comando para quitar la anulación:

adb shell am compat disable FORCE_RESIZE_APP <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

FORCE_NON_RESIZE_APP

Fuerza los paquetes a los que se aplica la anulación a que no puedan cambiar de tamaño y entren al modo de compatibilidad de tamaño en los cambios de configuración.

Cómo las apps pueden obtener el mismo resultado que la anulación

Establece el atributo android:resizeableActivity y la marca de metadatos android.supports_size_changes en false en el manifiesto de la app y declara una restricción de orientación o de relación de aspecto.

Cómo optimizar apps

Todas las apps que funcionan bien si se les cambia el tamaño deben tener android:resizeableActivity o android.supports_size_changes establecidos en true. Se deben mejorar otras apps para que funcionen bien cuando se les cambie el tamaño. Consulta android:resizeableActivity.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación y hacer que la app no pueda cambiar de tamaño:

adb shell am compat enable FORCE_NON_RESIZE_APP <package>

Comando para quitar la anulación:

adb shell am compat disable FORCE_NON_RESIZE_APP <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_MIN_ASPECT_RATIO

El controlador para todas las anulaciones que fuerzan una relación de aspecto mínima determinada.

Cómo las apps pueden obtener el mismo resultado que la anulación

Establece android:minAspectRatio a nivel de la actividad o la app.

Cómo optimizar apps

No establezcas restricciones de relación de aspecto en tu app. Asegúrate de que tu app admita diferentes tamaños de pantalla. Usa clases de tamaño de ventana para admitir diferentes diseños según la cantidad de espacio que tiene tu app en la pantalla. Consulta la API de WindowSizeClass de Compose y la API de WindowSizeClass de View.

Cómo inhabilitar o rechazar la anulación

Especifica una restricción de relación de aspecto o establece la marca de propiedad PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

Restringe la configuración de la app que fuerza una relación de aspecto mínima determinada para las actividades con orientación solo vertical. Está habilitado de forma predeterminada y solo tiene efecto si también se habilita OVERRIDE_MIN_ASPECT_RATIO.

Cómo las apps pueden obtener el mismo resultado que la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo optimizar apps

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo inhabilitar o rechazar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Marcas de propiedad para ajustar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_MIN_ASPECT_RATIO_MEDIUM

Establece la relación de aspecto mínima de la actividad en un valor medio (3:2).

Cómo las apps pueden obtener el mismo resultado que la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo optimizar apps

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo inhabilitar o rechazar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Marcas de propiedad para ajustar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_MIN_ASPECT_RATIO_LARGE

Establece la relación de aspecto mínima de la actividad en un valor alto (16:9).

Cómo las apps pueden obtener el mismo resultado que la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo optimizar apps

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo inhabilitar o rechazar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Marcas de propiedad para ajustar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>`

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN

Habilita el uso de la relación de aspecto de la pantalla dividida. Permite que una app use todo el espacio disponible en el modo de pantalla dividida, lo que evita el formato letterbox.

Cómo las apps pueden obtener el mismo resultado que la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo optimizar apps

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo inhabilitar o rechazar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Marcas de propiedad para ajustar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN

Inhabilita la anulación de relación de aspecto mínima en pantalla completa vertical para usar todo el espacio de pantalla disponible.

Cómo las apps pueden obtener el mismo resultado que la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo optimizar apps

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Cómo inhabilitar o rechazar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Marcas de propiedad para ajustar la anulación

Consulta OVERRIDE_MIN_ASPECT_RATIO.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT

Habilita la orientación vertical para todas las actividades del paquete. A menos que esté habilitado OVERRIDE_ANY_ORIENTATION, la anulación se usa solo cuando la actividad no especificó otra orientación fija.

Cómo las apps pueden obtener el mismo resultado que la anulación

Configura el atributo activity:screenOrientation del manifiesto o usa la API de Activity#setRequestedOrientation().

Cómo optimizar apps

Tu app debería admitir todas las orientaciones. Un cambio de orientación es un cambio de configuración que se puede controlar de dos maneras: permitir que el sistema destruya y vuelva a crear la app, o administrar los cambios de configuración por tu cuenta. Si administras los cambios de configuración por tu cuenta, el estado de la app se puede conservar mediante ViewModel. En casos muy limitados, puedes decidir bloquear la orientación solo en pantallas pequeñas, aunque es posible que no se ajuste ni permita al usuario rotar la app según sea necesario. En Android 12L y versiones posteriores, la configuración del dispositivo puede anular la orientación fija. Si quieres obtener más información para controlar los cambios de configuración y admitir todas las orientaciones, consulta Cómo administrar los cambios de configuración, Descripción general de ViewModel y Orientación de la app restringida en los teléfonos, pero no en los dispositivos con pantalla grande.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR

Habilita la orientación nosensor para todas las actividades del paquete. A menos que esté habilitado OVERRIDE_ANY_ORIENTATION, la anulación se usa solo cuando la actividad no especificó otra orientación fija.

Cómo las apps pueden obtener el mismo resultado que la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo optimizar apps

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo inhabilitar o rechazar la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Marcas de propiedad para ajustar la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT. ```

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

Habilita la orientación reverseLandscape para todas las actividades en el paquete. A menos que esté habilitado OVERRIDE_ANY_ORIENTATION, la anulación se usa solo cuando la actividad no especificó otra orientación fija.

Cómo las apps pueden obtener el mismo resultado que la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo optimizar apps

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo inhabilitar o rechazar la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Marcas de propiedad para ajustar la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_ANY_ORIENTATION

Permite que se anulen OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT, OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR y OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE para anular cualquier orientación.

Cómo las apps pueden obtener el mismo resultado que la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo optimizar apps

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo inhabilitar o rechazar la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Marcas de propiedad para ajustar la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_ANY_ORIENTATION <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_ANY_ORIENTATION <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA

Limita las opciones OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT, OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR y OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE, que solo tienen efecto cuando está activa la conexión de la cámara.

Cómo las apps pueden obtener el mismo resultado que la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo optimizar apps

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo inhabilitar o rechazar la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Marcas de propiedad para ajustar la anulación

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION

Restringe la orientación de la pantalla a la orientación natural horizontal cuando se cumplen las siguientes condiciones:

• La actividad está en pantalla completa.
• La propiedad del componente de inhabilitación PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE no está habilitada.
• El parámetro de configuración que el fabricante del dispositivo ignora la solicitud de orientación está habilitado para la pantalla.
• La orientación natural de la pantalla es horizontal.

Cómo las apps pueden obtener el mismo resultado que la anulación

No aplicable. El problema debería resolverse en la lógica de la aplicación.

Cómo optimizar apps

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_COMPAT_ALLOW_DISPLAY_ORIENTATION_OVERRIDE en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION

Habilita la política de compatibilidad que omite la actualización de la orientación de la app en respuesta a su llamada a Activity#setRequestedOrientation() cuando la app se reinicia o tiene un tratamiento de compatibilidad con la cámara activo.

Cómo las apps pueden obtener el mismo resultado que la anulación

Establece la marca de propiedad PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION en true.

Cómo optimizar apps

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_COMPAT_IGNORE_REQUESTED_ORIENTATION en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED

Habilita la política de compatibilidad que ignora la orientación solicitada de una app en respuesta a la llamada a Activity#setRequestedOrientation() más de dos veces en un segundo si una actividad no tiene formato letterbox para una orientación fija.

Cómo las apps pueden obtener el mismo resultado que la anulación

No aplicable. El problema debería resolverse en la lógica de la aplicación.

Cómo optimizar apps

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_COMPAT_ALLOW_IGNORING_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_RESPECT_REQUESTED_ORIENTATION

Excluye los paquetes de comportamiento ignorar la solicitud de orientación que los fabricantes de dispositivos pueden habilitar para un área de visualización o toda la pantalla.

Cómo las apps pueden obtener el mismo resultado que la anulación

No aplicable. El problema debería resolverse en la lógica de la aplicación.

Cómo optimizar apps

Consulta OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT.

Cómo inhabilitar o rechazar la anulación

No se puede rechazar. Inhabilitar la anulación puede ser peligroso si la app no es compatible con un dispositivo en el que el fabricante del dispositivo ignora la configuración de solicitudes de orientación. Comunícate con el equipo de Relaciones con Desarrolladores de Android para inhabilitar la anulación.

Marcas de propiedad para ajustar la anulación

No hay marcas de propiedad para esta anulación.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_RESPECT_REQUESTED_ORIENTATION <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

NEVER_SANDBOX_DISPLAY_APIS

Fuerza los paquetes para que nunca se aplique la zona de pruebas de la API de Display para una actividad del modo de compatibilidad de tamaño o letterbox. Las APIs de Display continúan proporcionando límites de área de visualización.

Cómo las apps pueden obtener el mismo resultado que la anulación

Para declarar que se puede cambiar el tamaño de las actividades, establece el atributo android:resizeableActivity del manifiesto en true o la marca de metadatos android.supports_size_changes en true.

Cómo optimizar apps

Las apps que declaran que su tamaño se puede cambiar en su totalidad no deben depender nunca del tamaño de visualización para posicionar elementos de la IU. Migra tu app a las APIs actualizadas que proporcionan WindowMetrics. Si usas Jetpack Compose, aprovecha la API de WindowSizeClass para dibujar la IU según el área de pantalla que tenga la app en la visualización actual. Consulta Clases de tamaño de ventana.

Cómo inhabilitar o rechazar la anulación

No se puede rechazar. Migra desde las APIs obsoletas.

Marcas de propiedad para ajustar la anulación

No hay marcas de propiedad para esta anulación.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable NEVER_SANDBOX_DISPLAY_APIS <package>

Comando para quitar la anulación:

adb shell am compat disable NEVER_SANDBOX_DISPLAY_APIS <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

ALWAYS_SANDBOX_DISPLAY_APIS

Fuerza los paquetes para que siempre tengan aplicada la zona de pruebas de la API de Display, independientemente del modo de renderización en ventanas. Las APIs de Display siempre proporcionan los límites de la app.

Cómo las apps pueden obtener el mismo resultado que la anulación

Para declarar que no se puede cambiar el tamaño de las actividades, establece el atributo android:resizeableActivity en false o la marca de metadatos android.supports_size_changes en false.

Cómo optimizar apps

Las apps que declaran que su tamaño se puede cambiar por completo nunca deben depender del tamaño de visualización para posicionar elementos de la IU. Migra tu app de las APIs obsoletas a las APIs actualizadas que proporcionan WindowMetrics. Consulta WindowMetricsCalculator.

Cómo inhabilitar o rechazar la anulación

No se puede rechazar. Migra desde las APIs obsoletas.

Marcas de propiedad para ajustar la anulación

No hay marcas de propiedad para esta anulación.

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable ALWAYS_SANDBOX_DISPLAY_APIS <package>

Comando para quitar la anulación:

adb shell am compat disable ALWAYS_SANDBOX_DISPLAY_APIS <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS

Fuerza los paquetes para que realicen una zona de pruebas de las siguientes APIs de View en los límites de actividad:

• getWindowVisibleDisplayFrame()
• getLocationOnScreen()

Cómo las apps pueden obtener el mismo resultado que la anulación

Resuelve el problema en el código de la aplicación usando APIs que proporcionen los límites de la ventana de la app y las compensaciones relacionadas con ella, en lugar de los límites de la pantalla del dispositivo y las compensaciones relacionadas con ella.

Cómo optimizar apps

Las apps deben usar las APIs de View, teniendo en cuenta la posibilidad de que se apliquen el formato letterbox y el modo multiventana a la app. Consulta WindowMetricsCalculator.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_COMPAT_ALLOW_SANDBOXING_VIEW_BOUNDS_APIS en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION

Inhabilita la rotación forzada. Mejora la experiencia del usuario en algunas apps.

Cómo las apps pueden obtener el mismo resultado que la anulación

Establece la marca de propiedad PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION en false.

Cómo optimizar apps

No dependas de la orientación almacenada en caché del sensor de la cámara ni de la información del dispositivo. Para obtener orientación sobre la compatibilidad de la cámara, consulta Presentación del visor de la cámara y Cómo brindar compatibilidad con superficies que pueden cambiar de tamaño en tu app de cámara.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_CAMERA_COMPAT_ALLOW_FORCE_ROTATION en true.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación, que quita la rotación forzada:

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>

Comando para quitar la anulación, que permite que ocurra la rotación forzada:

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH

Inhabilita la actualización de la actividad después de la rotación forzada. Mejora la experiencia del usuario cuando la actualización causa la pérdida de estado en las apps.

Cómo las apps pueden obtener el mismo resultado que la anulación

Establece la marca de propiedad PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH en false.

Cómo optimizar apps

Consulta OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_CAMERA_COMPAT_ALLOW_REFRESH en true.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación, que quita la actualización de la actividad:

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>

Comando para quitar la anulación, que permite la actualización de la actividad:

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE

Hace que los paquetes a los que se aplica realicen la actualización de la actividad con un ciclo onResume() → onPause() → onResume() en lugar de onResume() → onStop() → onResume() después de la rotación forzada de la compatibilidad de la cámara.

Cómo las apps pueden obtener el mismo resultado que la anulación

Establece la marca de propiedad PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE en true.

Cómo optimizar apps

Consulta OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT

Fuerza que la salida de la cámara se recorte a la orientación opuesta cuando la orientación vertical de la cámara no se alinea con la orientación natural del dispositivo. Muchas apps no controlan esta situación y muestran imágenes estiradas.

Cómo las apps pueden obtener el mismo resultado que la anulación

Establece la marca de propiedad PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT en true.

Cómo optimizar apps

Consulta OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_COMPAT_OVERRIDE_LANDSCAPE_TO_PORTRAIT en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación, que implementa el recorte de la cámara frontal interior:

adb shell am compat enable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>

Comando para quitar la anulación, que quita el recorte de la cámara frontal interior:

adb shell am compat disable OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

ANULAR_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION

Impide que las apps inhabiliten la función para compartir pantalla (consulta Proyección de contenido multimedia). Se implementa cuando las apps hacen un uso inadecuado de la API de createConfigForDefaultDisplay() para forzar la captura en pantalla completa y poner en riesgo la privacidad del usuario al exponer el contenido de las notificaciones, que se capturan con la pantalla completa, pero no cuando se comparte la pantalla de la app, y para todas las apps, independientemente del modo de renderización en ventanas.

Cómo las apps pueden obtener el mismo resultado que la anulación

Permite el comportamiento predeterminado de proyección de contenido multimedia (implementado en Android 14, nivel de API 34, con createScreenCaptureIntent()), lo que permite a los usuarios decidir si desean compartir la pantalla completa o una sola ventana de la app, independientemente del modo de renderización en ventanas. También puedes llamar a createScreenCaptureIntent(MediaProjectionConfig) con un argumento MediaProjectionConfig que se muestra desde una llamada a createConfigForUserChoice().

Cómo optimizar apps

Permite que los usuarios elijan si desean compartir toda la pantalla del dispositivo o una ventana de la app durante la proyección de contenido multimedia, que a partir de Android 14 es el comportamiento predeterminado.

Haz que tu app pueda cambiar de tamaño (resizeableActivity="true") para admitir el modo multiventana.

Cómo inhabilitar o rechazar la anulación

Debido a la seriedad de la privacidad del usuario, la app no puede inhabilitar ni rechazar esta anulación.

Marcas de propiedad para ajustar la anulación

Ningún contenido de este tipo

Comandos de adb para probar la anulación

Comando para aplicar la anulación, que cancela la inhabilitación de la app del uso compartido parcial de la pantalla (es decir, habilita el uso compartido parcial de la pantalla):

adb shell am compat enable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>

Para quitar la anulación, que permite que la app inhabilite la pantalla compartida parcial, haz lo siguiente:

adb shell am compat disable OVERRIDE_DISABLE_MEDIA_PROJECTION_SINGLE_APP_OPTION <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS

Habilita el envío de un enfoque falso a las apps sin enfoque en el modo de pantalla dividida. Algunos motores de juegos esperan a obtener el enfoque antes de dibujar el contenido de la app. Por lo tanto, el enfoque falso ayuda a las apps a evitar que permanezcan oscurecidas cuando se reanudan y aún no tienen enfoque.

Cómo las apps pueden obtener el mismo resultado que la anulación

Establece la marca de propiedad PROPERTY_COMPAT_ENABLE_FAKE_FOCUS en true.

Cómo optimizar apps

Puedes evitar este problema si tu app controla bien varias orientaciones y cambios de configuración. Prepara tu app para pantallas grandes siguiendo los lineamientos de calidad de las apps en pantallas grandes.

Si ejecutas el motor de juegos de Unity, actualiza a la versión 2019.4.40 o una versión posterior y vuelve a exportar el juego. Mantén la opción Resizable Window marcada en la configuración del reproductor de Android.

Cómo inhabilitar o rechazar la anulación

Establece la marca de propiedad PROPERTY_COMPAT_ENABLE_FAKE_FOCUS en false.

Marcas de propiedad para ajustar la anulación

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

Comandos de adb para probar la anulación

Comando para aplicar la anulación:

adb shell am compat enable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>

Comando para quitar la anulación:

adb shell am compat disable OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS <package>

Nota: Los comandos aplican o quitan la anulación solo de manera temporal.

Recursos adicionales

• Lineamientos sobre calidad de las apps en pantallas grandes
• Principales lineamientos de calidad de las apps