Brinda compatibilidad con cortes de pantalla

Un corte de pantalla es un área en algunos dispositivos que se extiende a la superficie de la pantalla para permitir una experiencia de borde a borde y proporcionar espacio para sensores importantes en la parte frontal del dispositivo. Android admite oficialmente cortes de pantalla en dispositivos con Android 9 (API nivel 28) y versiones posteriores. Ten en cuenta que los fabricantes de dispositivos también pueden admitir cortes de pantalla en dispositivos con Android 8.1 o versiones anteriores.

En este tema, se describe cómo implementar la compatibilidad con dispositivos con cortes, incluido cómo trabajar con el área de corte, es decir, el rectángulo de borde a borde en la superficie de la pantalla que contiene el corte.

Qué esperar en dispositivos con cortes de pantalla

Para garantizar la coherencia y la compatibilidad de apps, los dispositivos que ejecutan Android 9 deben garantizar el siguiente comportamiento de corte:

Un solo borde puede contener como máximo un corte.
Un dispositivo no puede tener más de dos cortes.
Un dispositivo no puede tener cortes en ninguno de sus bordes más largos.
En la orientación vertical sin marcas especiales establecidas, la barra de estado debe extenderse al menos hasta la altura del corte.
De manera predeterminada, en orientación horizontal o pantalla completa, toda el área de corte debe tener formato de letterbox.

Elige cómo administra tu app las áreas de corte

Si no deseas que tu contenido se superponga con un área de corte, asegúrate de que el contenido no se superponga con la barra de estado y de que la barra de navegación sea lo suficientemente grande. Si realizas procesamientos en el área de corte, puedes usar WindowInsets.getDisplayCutout() para recuperar un objeto DisplayCutout que contiene las inserciones seguras y el cuadro de límite para cada corte. Estas API te permiten verificar si el contenido se superpone con el corte para que puedas reposicionarlo si es necesario.

Android también te permite controlar si quieres mostrar contenido dentro del área de corte. El atributo de diseño de ventana layoutInDisplayCutoutMode controla cómo se dibuja tu contenido en el área de corte. Puedes establecer layoutInDisplayCutoutMode en uno de los siguientes valores:

LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT: Este es el comportamiento predeterminado, como se describió anteriormente. El contenido se procesa en el área de corte mientras está en modo vertical, pero el contenido se muestra en formato letterbox en modo horizontal.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: El contenido se procesa en el área de corte en los modos vertical y horizontal.
LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: El contenido nunca se procesa en el área de corte.

Puedes configurar el modo de corte de manera programática o estableciendo un estilo en la actividad. En el siguiente ejemplo, se define un estilo que puedes usar para aplicar el atributo LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES a la actividad.

    <style name="ActivityTheme">
      <item name="android:windowLayoutInDisplayCutoutMode">
        shortEdges <!-- default, shortEdges, never -->
      </item>
    </style>

En las secciones incluidas a continuación, se describen los diferentes modos de corte con más detalle.

Comportamiento predeterminado

De manera predeterminada, en el modo vertical sin marcas especiales establecidas, la barra de estado en un dispositivo con un corte se cambia de tamaño para que sea al menos tan alta como el corte, y el contenido se muestra en el área que está debajo. En el modo horizontal o de pantalla completa, la ventana de la app está en formato letterbox para que no aparezca contenido en el área de corte.

Procesa contenido en áreas de corte del borde corto

Para algunos contenidos, como videos, fotos, mapas y juegos, el procesamiento en el área de corte puede ser una excelente manera de proporcionar una experiencia más envolvente y de borde a borde para los usuarios. Con LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, el contenido se extiende al área de corte en el borde corto de la pantalla tanto en el modo vertical como en el horizontal, independientemente de si las barras del sistema están ocultas o visibles. Ten en cuenta que la ventana nunca puede extenderse a un área de corte en los bordes largos de la pantalla. Cuando utilices este modo, asegúrate de que ningún contenido importante se superponga con el área de corte.

Ten en cuenta que Android podría no permitir que la vista de contenido se superponga con las barras del sistema. Para anular este comportamiento y forzar que el contenido se extienda al área de corte, aplica cualquiera de las siguientes marcas a la visibilidad de la vista mediante el método View.setSystemUiVisibility(int):

SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
SYSTEM_UI_FLAG_LAYOUT_STABLE

A continuación, se incluyen algunos ejemplos de LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES:

procesamiento de contenido en el área de corte mientras se usa el modo vertical

procesamiento de contenido en el área de corte mientras se usa el modo horizontal

Ten en cuenta que se considera que un corte en la esquina está en el borde corto, por lo que se aplica el mismo comportamiento:

Nunca proceses contenido en el área de corte de la pantalla

Con LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER, no se permite que la ventana se superponga con el área de corte.

Este modo se debe usar con ventanas que configuran transitoriamente View.SYSTEM_UI_FLAG_FULLSCREEN o View.SYSTEM_UI_FLAG_HIDE_NAVIGATION para evitar realizar otro diseño de la ventana cuando la marca está activada o desactivada.

Consulta ejemplos de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER a continuación:

Modo especial

Algunos dispositivos que ejecutan Android 8.1 (API nivel 27) o versiones anteriores admiten un modo especial que permite a los usuarios extender una app de pantalla completa o apaisada en formato letterbox en el área de corte. En general, este modo se controla con un botón de activación en la barra de navegación que presenta un diálogo que requiere confirmación para extender la pantalla.

Prácticas recomendadas para admitir el corte de pantalla

Cuando trabajes con cortes de pantalla, asegúrate de considerar lo siguiente:

No permitas que el área de corte oculte textos, controles o informaciones importantes.
No coloques ni extiendas en el área de corte ningún elemento interactivo que requiera reconocimiento táctil avanzado. La sensibilidad al tacto puede ser menor en el área de corte.
Evita codificar la altura de la barra de estado, ya que eso puede generar contenido superpuesto o cortado. Siempre que sea posible, usa WindowInsetsCompat para recuperar la altura de la barra de estado y determinar el relleno adecuado para tu contenido.
No supongas que la app tiene toda la ventana. En su lugar, confirma la ubicación utilizando View.getLocationInWindow(). No uses View.getLocationOnScreen().
Asegúrate de manejar adecuadamente las transiciones para entrar al modo de pantalla completa y salir de él. esta entrada de blog de desarrolladores de Android.
Con el comportamiento de corte predeterminado en modo vertical, si el área de corte está en el borde superior y la ventana no configuró FLAG_FULLSCREEN ni View.SYSTEM_UI_FLAG_FULLSCREEN, la ventana puede extenderse dentro del área de corte. De manera similar, si el área de corte está en el borde inferior y la ventana no estableció View.SYSTEM_UI_FLAG_HIDE_NAVIGATION, la ventana puede extenderse hacia el área de corte. En los modos de pantalla horizontal o completa, la ventana se presenta de manera que no se superponga con el área de corte.
Usa los modos de corte shortEdges o never si tu app necesita entrar al modo de pantalla completa y salir de él. El comportamiento de corte predeterminado puede hacer que el contenido de tu app se mueva hacia arriba y hacia abajo durante las transiciones, como se muestra en la imagen incluida a continuación:
En el modo de pantalla completa, ten cuidado al usar las coordenadas de ventana versus pantalla, ya que la app no ocupa toda la pantalla cuando está en formato letterbox. Debido a ese formato, las coordenadas del origen de la pantalla ya no son las mismas que las coordenadas del origen de la ventana. Puedes transformar las coordenadas de la pantalla en las coordenadas de la vista según sea necesario con getLocationOnScreen(). En la imagen incluida a continuación, se muestra cómo se diferencian las coordenadas cuando el contenido está en formato letterbox:

Cuando utilices MotionEvent, usa MotionEvent.getX() y MotionEvent.getY() para evitar problemas de coordenadas similares. No uses MotionEvent.getRawX() ni MotionEvent.getRawY().

Prueba cómo se procesa tu contenido

cómo simular un corte de pantalla en el emulador

Asegúrate de probar todas las pantallas y experiencias de tu app. Si es posible, pruébalas en dispositivos con diferentes tipos de cortes. Si no tienes un dispositivo con un corte, puedes simular algunas configuraciones de corte comunes en cualquier dispositivo o emulador que ejecute Android 9. Para ello, haz lo siguiente:

Habilita las opciones para desarrolladores.
En la pantalla Opciones para desarrolladores, desplázate hacia abajo hasta la sección Dibujo y selecciona Simular una pantalla con un corte.
Selecciona el tipo de corte.

Recursos adicionales

Para obtener más información acerca de la compatibilidad con el corte de pantalla, consulta los siguientes vínculos: