Información acerca de las inserciones de ventana

La plataforma de Android es responsable de dibujar la IU del sistema, como la barra de estado y la barra de navegación. Esta IU del sistema se muestra independientemente de la app que use el usuario.

WindowInsets proporciona información sobre la IU del sistema para garantizar que tu app dibuje en el área correcta y que la IU del sistema no oculte tu IU.

Figura 1: Ir de borde a borde para dibujar detrás de las barras del sistema

En Android 14 (nivel de API 34) y versiones anteriores, la IU de tu app no se dibuja debajo de las barras del sistema ni de los cortes de pantalla de forma predeterminada.

En Android 15 (nivel de API 35) y versiones posteriores, tu app se dibuja debajo de las barras del sistema y los cortes de pantalla una vez que se orienta al SDK 35. Esto genera una experiencia del usuario más fluida y permite que tu app aproveche al máximo el espacio disponible en la ventana.

Mostrar contenido detrás de la IU del sistema se denomina ir de borde a borde. En esta página, obtendrás información sobre los diferentes tipos de inserciones, cómo ir de borde a borde y cómo usar las APIs de inserción para animar tu IU y asegurarte de que los elementos de la IU del sistema no oculten el contenido de tu app.

Importante: Se aplica el diseño de borde a borde en Android 15 y versiones posteriores una vez que tu app se orienta al SDK 35. Si tu app aún no es de borde a borde, es posible que se oculten partes de ella y que debas controlar las inserciones. Según la app, este trabajo puede ser significativo o no. El componente Scaffold de Material 3 puede reducir el trabajo necesario para que sea compatible con la aplicación de la función de borde a borde de Android 15. Consulta Cómo crear un componente de Scaffold para mantener unida la IU.

Conceptos básicos de los elementos de inserción

Cuando una app se muestra de borde a borde, debes asegurarte de que la IU del sistema no oculte el contenido y las interacciones importantes. Por ejemplo, si un botón se coloca detrás de la barra de navegación, es posible que el usuario no pueda hacer clic en él.

El tamaño de la IU del sistema y la información sobre dónde se coloca se especifican con inserciones.

Cada parte de la IU del sistema tiene un tipo de inserción correspondiente que describe su tamaño y dónde se coloca. Por ejemplo, las inserciones de la barra de estado proporcionan el tamaño y la posición de la barra de estado, mientras que las inserciones de la barra de navegación proporcionan el tamaño y la posición de la barra de navegación. Cada tipo de inserción consta de cuatro dimensiones de píxeles: superior, izquierda, derecha e inferior. Estas dimensiones especifican hasta dónde se extiende la IU del sistema desde los lados correspondientes de la ventana de la app. Por lo tanto, para evitar que se superponga con ese tipo de IU del sistema, la IU de la app debe insertarse en esa cantidad.

Estos tipos de inserciones integradas de Android están disponibles a través de WindowInsets:

WindowInsets.statusBars	Son los elementos de inserción que describen las barras de estado. Estas son las barras superiores de la IU del sistema que contienen íconos de notificaciones y otros indicadores.
WindowInsets.statusBarsIgnoringVisibility	Son los elementos de inserción de la barra de estado para cuando están visibles. Si las barras de estado están ocultas (debido a que se ingresó al modo de pantalla completa envolvente), los márgenes de la barra de estado principal estarán vacíos, pero estos márgenes no estarán vacíos.
WindowInsets.navigationBars	Son las inserciones que describen las barras de navegación. Estas son las barras de la IU del sistema que se encuentran en el lado izquierdo, derecho o inferior del dispositivo, y describen la barra de tareas o los íconos de navegación. Estos pueden cambiar en el entorno de ejecución según el método de navegación preferido del usuario y la interacción con la barra de tareas.
WindowInsets.navigationBarsIgnoringVisibility	Son los elementos de inserción de la barra de navegación para cuando están visibles. Si las barras de navegación están ocultas (debido a que se ingresó al modo de pantalla completa envolvente), los márgenes de la barra de navegación principal estarán vacíos, pero estos márgenes no estarán vacíos.
WindowInsets.captionBar	Es el elemento de inserción que describe la decoración de la ventana de la IU del sistema si se encuentra en una ventana de formato libre, como la barra de título superior.
WindowInsets.captionBarIgnoringVisibility	Son las inserciones de la barra de subtítulos para cuando están visibles. Si las barras de subtítulos están ocultas, los márgenes de la barra de subtítulos principal estarán vacíos, pero estos márgenes no estarán vacíos.
WindowInsets.systemBars	Es la unión de las inserciones de la barra del sistema, que incluyen las barras de estado, las barras de navegación y la barra de subtítulos.
WindowInsets.systemBarsIgnoringVisibility	Son los elementos de inserción de la barra del sistema para cuando están visibles. Si las barras del sistema están ocultas (debido a que se ingresó al modo envolvente de pantalla completa), los márgenes de la barra principal del sistema estarán vacíos, pero estos márgenes no estarán vacíos.
WindowInsets.ime	Son las inserciones que describen la cantidad de espacio en la parte inferior que ocupa el teclado en pantalla.
WindowInsets.imeAnimationSource	Son las inserciones que describen la cantidad de espacio que ocupaba el teclado en pantalla antes de la animación actual del teclado.
WindowInsets.imeAnimationTarget	Son las inserciones que describen la cantidad de espacio que ocupará el teclado en pantalla después de la animación actual del teclado.
WindowInsets.tappableElement	Es un tipo de inserciones que describe información más detallada sobre la IU de navegación y que indica la cantidad de espacio en el que el sistema, y no la app, controlará las "presiones". En el caso de las barras de navegación transparentes con navegación por gestos, se puede presionar algunos elementos de la app a través de la IU de navegación del sistema.
WindowInsets.tappableElementIgnoringVisibility	Son los elementos de inserción de elementos que se pueden presionar cuando están visibles. Si los elementos que se pueden presionar están ocultos (debido a que se ingresó al modo de pantalla completa envolvente), los márgenes del elemento principal que se puede presionar estarán vacíos, pero estos márgenes no estarán vacíos.
WindowInsets.systemGestures	Son los elementos de inserción que representan la cantidad de elementos de inserción en los que el sistema interceptará los gestos de navegación. Las apps pueden especificar de forma manual que se controle una cantidad limitada de estos gestos con Modifier.systemGestureExclusion.
WindowInsets.mandatorySystemGestures	Un subconjunto de los gestos del sistema que siempre controlará el sistema y que no se pueden inhabilitar con Modifier.systemGestureExclusion.
WindowInsets.displayCutout	Son los recuadros que representan la cantidad de espaciado necesario para evitar la superposición con un corte de pantalla (un corte en forma de gota o un corte circular).
WindowInsets.waterfall	Son los márgenes que representan las áreas curvas de una pantalla en cascada. Una pantalla de cascada tiene áreas curvas a lo largo de los bordes de la pantalla, donde esta comienza a envolver los lados del dispositivo.

Estos tipos se resumen en tres tipos de inserciones "seguras" que garantizan que el contenido no se oculte:

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

Estos tipos de inserciones "seguras" protegen el contenido de diferentes maneras, según las inserciones de la plataforma subyacente:

• Usa WindowInsets.safeDrawing para proteger el contenido que no se debe dibujar debajo de ninguna IU del sistema. Este es el uso más común de las inserciones: evitar dibujar contenido que la IU del sistema oculte (ya sea de forma parcial o total).
• Usa WindowInsets.safeGestures para proteger el contenido con gestos. Esto evita que los gestos del sistema entren en conflicto con los gestos de la app (como los de las hojas inferiores, los carruseles o los juegos).
• Usa WindowInsets.safeContent como una combinación de WindowInsets.safeDrawing y WindowInsets.safeGestures para asegurarte de que el contenido no tenga superposición visual ni de gestos.