Cómo brindar compatibilidad con cortes de pantalla

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

Un corte de pantalla es un área en algunos dispositivos que se extiende hasta la superficie de la pantalla. Permite una experiencia de borde a borde al mismo tiempo que proporciona espacio para sensores importantes en la parte frontal del dispositivo.

Android admite cortes de pantalla en dispositivos que ejecutan 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.

Una imagen que muestra un ejemplo de recorte de pantalla en la parte superior central
Figura 1: 1 Corte de pantalla.

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

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

También puedes determinar si el contenido está colocado 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:

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 configuradas, se cambia el tamaño de la barra de estado de un dispositivo con un corte para que sea al menos tan alta como el corte, y tu contenido se muestra en el área que aparece a continuación. En el modo horizontal o de pantalla completa, la ventana de la app tiene formato letterbox para que no se muestre nada de tu contenido en el área de corte.

Procesa contenido en áreas de corte del borde corto

En el caso de algunos contenidos, como videos, fotos, mapas y juegos, la renderización en el área de corte puede ser una excelente manera de brindar a los usuarios una experiencia más envolvente y de borde a borde. Con LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, el contenido se extiende en el área de corte en el borde corto de la pantalla tanto en modo vertical como horizontal, independientemente de si las barras del sistema están ocultas o visibles. Cuando uses este modo, asegúrate de que no haya contenido importante que 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 posición vertical:

Una imagen que muestra la renderización de contenido en el área de corte mientras se usa el modo vertical
Figura 2: Renderización de contenido en el área de corte mientras está en modo vertical

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

Una imagen que muestra la renderización de contenido en el área de corte mientras se usa el modo horizontal
Figura 3: Renderización de contenido en el área de corte mientras se usa en modo horizontal

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

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

Una imagen que muestra un dispositivo con un recorte de esquina
Figura 4: Un dispositivo con un corte de esquina.

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.

A continuación, se muestra un ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en orientación 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.

A continuación, se muestra un ejemplo de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en modo horizontal:

Una imagen que muestra LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER para la orientación 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 elementos fundamentales de la IU. No dejes que el área de corte oculte texto, controles ni otra información importante.
  • No coloques ni extiendas ningún elemento interactivo que requiera reconocimiento detallado en el área de corte. La sensibilidad táctil 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 apropiado para aplicar a tu contenido. Evita codificar la altura de la barra de estado, ya que esto puede generar contenido superpuesto o cortado.

    Una imagen que muestra el contenido cortado en la parte superior por una configuración incorrecta de las inserciones
    Figura 7: Usa WindowInsetsCompat para evitar que se superponga o corte el contenido.
  • Usa View.getLocationInWindow() para determinar cuánto espacio de ventana usa tu app. No supongas que la app usa toda la ventana ni View.getLocationOnScreen().

  • Usa los modos de corte shortEdges o never si tu app necesita pasar 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. Como resultado, el contenido se mueve hacia arriba y hacia abajo durante las transiciones, como se muestra en el siguiente ejemplo.

    Una imagen en la que se 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 con el uso de coordenadas de ventana frente a pantalla, ya que tu app no usa toda la pantalla 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:

    Imagen que muestra las coordenadas de la ventana frente a la pantalla cuando el contenido está en formato letterbox.
    Figura 9: Coordenadas de ventana frente a pantalla 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, haz pruebas en dispositivos con diferentes tipos de cortes. Si no tienes un dispositivo con un corte, puedes simular las 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 que prueban cómo se renderiza tu contenido.

Recursos adicionales