Cómo brindar compatibilidad con cortes de pantalla

Prueba hacerlo con Compose
Jetpack Compose es el kit de herramientas de IU recomendado para Android. Obtén información para trabajar con cortes de pantalla en Compose.
Cortes de pantalla en Compose →

Un corte de pantalla es un área en algunos dispositivos 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 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.

Una imagen que muestra un ejemplo de corte de pantalla centrado en la parte superior
Figura 1. 1 Corte de pantalla

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, usa WindowInsetsCompat.getDisplayCutout() para recuperar un DisplayCutout objeto que contiene las inserciones seguras y el cuadro delimitador para cada corte. Estas APIs te permiten verificar si tu contenido se superpone con el corte para que puedas cambiar su posición si es necesario.

También puedes determinar si el contenido se diseña detrás del área de corte. El layoutInDisplayCutoutMode atributo de diseño de ventana controla cómo se dibuja tu contenido en el área de corte. Puedes configurar layoutInDisplayCutoutMode en uno de los siguientes valores:

  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT: El contenido se procesa en el área de corte cuando el corte de pantalla está contenido en una barra del sistema. De lo contrario, la ventana no se superpone con el corte de pantalla. Por ejemplo, el contenido puede mostrarse en formato letterbox cuando se muestra en modo horizontal. Si tu app se orienta al SDK 35, esto se interpreta como ALWAYS para ventanas no flotantes.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS: Siempre se permite que el contenido se extienda a las áreas de corte. Si tu app se orienta al SDK 35 y se ejecuta en un dispositivo Android 15, este es el único modo permitido para que las ventanas no flotantes garanticen una pantalla de borde a borde.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES: El contenido se procesa en el área de corte en los modos vertical y horizontal. No lo uses para ventanas flotantes. Si tu app se orienta al SDK 35, esto se interpreta como ALWAYS para ventanas no flotantes.
  • LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER: El contenido nunca se procesa en el área de corte. Si tu app se orienta al SDK 35, esto se interpreta como ALWAYS para ventanas no flotantes.

Puedes configurar el modo de corte de forma programática o configurando 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

Si tu app se orienta al SDK 35 y se ejecuta en un dispositivo Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS es el comportamiento predeterminado, y LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT se interpreta como LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS para ventanas no flotantes.

De lo contrario, LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT es el valor predeterminado.

Procesa contenido en áreas de corte del borde corto

Si tu app se orienta al SDK 35 y se ejecuta en un dispositivo Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES se interpreta como LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS para ventanas no flotantes.

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. Cuando utilices 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 modo vertical:

Una imagen que muestra el procesamiento de contenido en el área de corte mientras se usa el modo vertical
Figura 2. Procesamiento de contenido en el área de corte mientras se usa el modo vertical

La siguiente imagen es un ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES para un dispositivo en modo horizontal:

Una imagen que muestra el procesamiento de contenido en el área de corte mientras se usa el modo horizontal
Figura 3. Procesamiento de contenido en el área de corte mientras se usa el modo horizontal

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

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

Imagen que muestra un dispositivo con un corte de esquina
Figura 4: Un dispositivo con un corte de esquina

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

Si tu app se orienta al SDK 35 y se ejecuta en un dispositivo Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER se interpreta como LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS para ventanas no flotantes.

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

El siguiente es un ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en modo vertical:

Una imagen que muestra LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER para el modo vertical
Figura 5. Ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER para el modo vertical.

El siguiente es un ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en modo horizontal:

Una imagen que muestra LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER para el modo horizontal
Figura 6: 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 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.

  • Cuando sea posible, usa WindowInsetsCompat para recuperar la altura de la barra de estado y determinar el padding adecuado para aplicar a tu contenido. Evita codificar la altura de la barra de estado, ya que esto puede provocar superposiciones o cortes de contenido.

    Imagen que muestra el contenido cortado en la parte superior debido a una configuración incorrecta de las inserciones
    Figura 7. Usa WindowInsetsCompat para evitar superponer o cortar contenido.

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

  • Usa los modos de corte always, 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 procese 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.

    Imagen que muestra el contenido que se mueve hacia arriba y hacia abajo durante las transiciones.
    Figura 8: Ejemplo de contenido que se mueve hacia arriba y hacia abajo durante las transiciones

  • En el modo envolvente, 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 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 imagen incluida a continuación, se muestra cómo se diferencian las coordenadas cuando el contenido está en formato letterbox:

    Imagen que muestra las coordenadas de la ventana en comparación con las de la pantalla cuando el contenido está en formato letterbox.
    Figura 9: Coordenadas de ventana versus pantalla cuando el contenido está en formato letterbox

  • Cuando manejes 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. Para ello, haz lo siguiente:

  1. Habilita las 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.

    Una imagen que muestra cómo simular un corte de pantalla en el emulador
    Figura 10: Opciones para desarrolladores para probar cómo se procesa tu contenido

Recursos adicionales