Cómo brindar compatibilidad con cortes de pantalla

Prueba el método de Compose

Jetpack Compose es el kit de herramientas de IU recomendado para Android. Aprende a trabajar con cortes de pantalla en Compose.

Recortes de pantalla en Compose →

En algunos dispositivos, un corte de pantalla es un área que se extiende a la superficie de la pantalla. Permite una experiencia de borde a borde y proporciona espacio para sensores importantes en la parte frontal del dispositivo.

Android admite cortes de pantalla en dispositivos con Android 9 (nivel de API 28) y versiones posteriores. Sin embargo, los fabricantes de dispositivos también pueden admitir cortes de pantalla en dispositivos con Android 8.1 o versiones anteriores.

En este documento, se describe cómo implementar la compatibilidad para 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.

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

Si no quieres que tu contenido se superponga con un área de corte, por lo general, es suficiente con asegurarte de que no se superponga con la barra de estado y la barra de navegación. Si renderizas en el área de corte, usa WindowInsetsCompat.getDisplayCutout() para recuperar un objeto DisplayCutout que contenga las inserciones seguras y el cuadro delimitador de cada corte. Estas APIs te permiten verificar si tu contenido se superpone con el corte para que puedas reposicionarlo si es necesario.

También puedes determinar si el contenido se coloca detrás 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_ALWAYS: El contenido siempre se puede extender a las áreas de corte. Este es el modo predeterminado para los dispositivos que ejecutan Android 15 o versiones posteriores.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: El contenido se renderiza en el área de corte en los modos vertical y horizontal. No lo uses para ventanas flotantes.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: El contenido nunca se renderiza en el área de corte.

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

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

En las siguientes secciones, se describen los diferentes modos de corte con más detalle.

Comportamiento predeterminado

De forma 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 se encuentra debajo. En el modo horizontal o de pantalla completa, la ventana de la app tiene formato letterbox para que no se muestre ningún contenido en el área de corte.

Procesa contenido en áreas de corte del borde corto

En el caso de cierto contenido, como videos, fotos, mapas y juegos, la renderización en el área de corte puede ser una excelente manera de proporcionar a los usuarios una experiencia más envolvente de borde a borde. 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 formato vertical como horizontal, independientemente de si las barras del sistema están ocultas o visibles. Cuando uses este modo, asegúrate de que ningún contenido importante se superponga con el área de corte.

La siguiente imagen es un ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES para un dispositivo en orientación vertical:

La siguiente imagen es un ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES para un dispositivo en orientación horizontal:

En este modo, la ventana se extiende debajo de cortes en el borde corto de la pantalla, tanto en el modo vertical como en el horizontal, independientemente de si la ventana oculta las barras del sistema.

Se considera que un corte en la esquina está en el borde corto:

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

Con LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER, la ventana nunca puede superponerse con el área de corte.

El siguiente es un ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en formato vertical:

El siguiente es un ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en modo horizontal:

Prácticas recomendadas para admitir el corte de pantalla

Cuando trabajes con cortes de pantalla, ten en cuenta lo siguiente:

• Ten en cuenta la ubicación de los elementos críticos de la IU. No permitas que el área de corte oculte texto, controles o información importante.
• No coloques ni extiendas ningún elemento interactivo que requiera un reconocimiento táctil en el área de corte. La sensibilidad al tacto puede ser más baja en el área de corte.

• Cuando sea posible, usa WindowInsetsCompat para recuperar la altura de la barra de estado y determinar el padding apropiado que se aplicará a tu contenido. Evita codificar la altura de la barra de estado, ya que esto puede generar contenido superpuesto o cortado.

  

• Usa View.getLocationInWindow() para determinar cuánto espacio de ventana usa tu app. No supongas que la app usará toda la ventana ni uses View.getLocationOnScreen().

• Usa los modos de corte shortEdges o never si tu app necesita entrar al modo envolvente y salir de él. El comportamiento de corte predeterminado puede hacer que el contenido de tu app se renderice en el área de corte mientras las barras del sistema están presentes, pero no en el modo envolvente. Esto hace que el contenido se mueva hacia arriba y hacia abajo durante las transiciones, como se muestra en el siguiente ejemplo.

  

• En el modo envolvente, ten cuidado cuando uses las coordenadas de ventana frente a las de pantalla, ya que la app no usa toda la pantalla cuando está en formato letterbox. Debido al formato letterbox, las coordenadas del origen de la pantalla 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 siguiente imagen, se muestra cómo difieren las coordenadas cuando el contenido está en formato letterbox:

  

• Cuando controles 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

Prueba todas las pantallas y experiencias de tu app. Si es posible, prueba en dispositivos con diferentes tipos de cortes. Si no tienes un dispositivo con un corte, puedes simular configuraciones de corte comunes en cualquier dispositivo o emulador que ejecute Android 9 o versiones posteriores de la siguiente manera:

1. Habilita Opciones para desarrolladores.
2. En la pantalla Opciones para desarrolladores, desplázate hacia abajo hasta la sección Dibujo y selecciona Simular una pantalla con un corte.

3. Selecciona el tipo de corte.

   

Recursos adicionales

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES