Cómo mostrar el contenido de borde a borde en tu app y controlar las inserciones de ventana en Compose

La plataforma de Android es responsable de dibujar la IU del sistema, como la barra de estado y la de navegación. Se muestra la IU del sistema independientemente de cuál la app que el usuario utiliza.

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

Figura 1: Se usa 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 las barras del sistema y 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 muestra recortes una vez que se orienta al SDK 35. Esto da como resultado una una experiencia del usuario fluida y que permita que tu aplicación aproveche al máximo el espacio de ventana disponible.

Mostrar contenido detrás de la IU del sistema se denomina borde a borde. En este aprenderás 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 garantizar que el contenido de tu app no se obstruyan los elementos de la IU del sistema.

Importante: El diseño de borde a borde se aplica en Android 15 y versiones posteriores una vez que tu app se segmenta para el SDK 35. Si tu aplicación aún no está de borde a borde, es posible que algunas partes oculto y debes controlar las inserciones. Según la app, este trabajo puede ser significativo o no. El componente andamiaje de Material 3 puede reducir el trabajo necesario para ser compatible con la aplicación forzosa de borde a borde de Android 15. Consulta Crea un componente de andamiaje para mantener juntas la IU.

Aspectos básicos de la inserción

Cuando una app va de borde a borde, debes asegurarte de que el contenido y las interacciones no quedan ocultas por la IU del sistema. 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 mediante insertos.

Cada parte de la IU del sistema tiene un tipo de inserción correspondiente que describe lo siguiente: su tamaño y dónde está ubicado. 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, izquierdo, derecho 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 superponerse 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	Las inserciones 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	Los rellenos de la barra de estado para cuando están visibles Si las barras de estado están ocultas (debido al modo de pantalla completa envolvente), las inserciones de la barra de estado principal estarán vacías, pero no lo estarán.
WindowInsets.navigationBars	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 que describen la barra de tareas o los íconos de navegación. Estas pueden cambiar en el tiempo de ejecución en función del método de navegación preferido del usuario y la interacción con la barra de tareas.
WindowInsets.navigationBarsIgnoringVisibility	Las inserciones de la barra de navegación para cuando estén visibles Si las barras de navegación están ocultas (debido al modo de pantalla completa envolvente), las inserciones de la barra de navegación principal estarán vacías, pero no lo estarán.
WindowInsets.captionBar	El inserto que describe la decoración de la ventana de la IU del sistema si está en una ventana de formato libre, como la barra de título superior.
WindowInsets.captionBarIgnoringVisibility	La barra de subtítulos se inserta cuando están visibles. Si las barras de subtítulos están ocultas, los recuadros de la barra de subtítulos principal estarán vacíos, pero no lo estarán.
WindowInsets.systemBars	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 leyendas.
WindowInsets.systemBarsIgnoringVisibility	La barra del sistema se inserta para cuando están visibles. Si las barras del sistema están ocultas (debido al modo de pantalla completa envolvente), las inserciones de la barra principal del sistema estarán vacías, pero no lo estarán.
WindowInsets.ime	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 del teclado actual.
WindowInsets.imeAnimationTarget	Son las inserciones que describen la cantidad de espacio que ocupará el teclado en pantalla después de la animación del teclado actual.
WindowInsets.tappableElement	Un tipo de inserciones que describen información más detallada sobre la IU de navegación, que proporciona la cantidad de espacio en la que se presionan los elementos son del sistema, no de la app. En el caso de las barras de navegación transparentes con navegación por gestos, algunos elementos de la app se pueden presionar a través de la IU de navegación del sistema.
WindowInsets.tappableElementIgnoringVisibility	Las inserciones de elementos que se pueden presionar para cuando son visibles Si los elementos que se pueden presionar están ocultos (debido al modo de pantalla completa envolvente), las inserciones de elementos principales que se pueden presionar estarán vacías, pero estas inserciones no estarán vacías.
WindowInsets.systemGestures	Las inserciones que representan la cantidad de inserciones en las que el sistema interceptará gestos para la navegación Las apps pueden especificar manualmente la forma de controlar una cantidad limitada de estos gestos a través de Modifier.systemGestureExclusion.
WindowInsets.mandatorySystemGestures	Es un subconjunto de los gestos del sistema que el sistema siempre controlará y que no se puede inhabilitar a través de Modifier.systemGestureExclusion.
WindowInsets.displayCutout	Las inserciones que representan la cantidad de espacio necesaria para evitar superponerse con un corte en la pantalla (muesca o orificio)
WindowInsets.waterfall	Los recuadros 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 la pantalla comienza a ajustarse a 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

Se consideran "seguros" los tipos de inserción protegen el contenido de diferentes maneras, según el las inserciones subyacentes de la plataforma:

• Usa WindowInsets.safeDrawing para proteger el contenido que no se debe dibujar. debajo de cualquier IU del sistema. Este es el uso más común de las inserciones: para evitar dibujar contenido que está oscurecido por la IU del sistema (ya sea de forma parcial o completamente).
• Usa WindowInsets.safeGestures para proteger el contenido con gestos. De esta manera, se 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 garantizar contenido no tiene superposición visual ni de gestos.

Configuración de las inserciones

Para permitir que tu app tenga control total sobre dónde dibuja el contenido, sigue estos pasos de configuración. Sin estos pasos, tu app podría dibujar colores negros o sólidos detrás de la de la IU del sistema o no animarlo de forma síncrona con el teclado en pantalla.

1. Orienta la app al SDK 35 o versiones posteriores para aplicar de manera forzosa el borde a borde en Android 15 y versiones posteriores. Tu app se muestra detrás de la IU del sistema. Puedes ajustar la IU de tu app controlando inserciones.
2. De manera opcional, llama a enableEdgeToEdge() en Activity.onCreate(), que permite que tu app sea de borde a borde en versiones anteriores Versiones de Android

3. Establece android:windowSoftInputMode="adjustResize" en la entrada AndroidManifest.xml de tu actividad. Este parámetro de configuración permite que tu app reciba el tamaño del IME de software como inserciones, que puedes usar para rellenar y diseñar el contenido de forma adecuada cuando el IME aparece y desaparece en tu app.

   <!-- in your AndroidManifest.xml file: -->
   <activity
     android:name=".ui.MainActivity"
     android:label="@string/app_name"
     android:windowSoftInputMode="adjustResize"
     android:theme="@style/Theme.MyApplication"
     android:exported="true">
   

APIs de Compose

Una vez que tu actividad haya tomado el control del control de todas las inserciones, puedes usar Compose. para garantizar que el contenido no esté oscurecido y que los elementos interactivos no se superponen con la IU del sistema. Estas APIs también sincronizan el diseño de tu app con cambios en la inserción.

Por ejemplo, este es el método más básico para aplicar las inserciones al contenido. de toda la app:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    enableEdgeToEdge()

    setContent {
        Box(Modifier.safeDrawingPadding()) {
            // the rest of the app
        }
    }
}
InsetsSnippets.kt

Este fragmento aplica las inserciones de ventana safeDrawing como padding alrededor del todo el contenido de la app. Si bien esto garantiza que los elementos interactivos no se superponen con la IU del sistema, también significa que ninguna app se dibujará detrás la IU del sistema para lograr un efecto de borde a borde. Para aprovechar al máximo la totalidad ventana, debes ajustar dónde se aplican las inserciones en cada pantalla o componente por componente.

Todos estos tipos de inserción se animan automáticamente con animaciones IME y adaptarlos al nivel de API 21. Por extensión, todos los diseños que usan estas inserciones también se anima automáticamente a medida que cambian los valores de inserción.

Hay dos formas principales de usar estos tipos de inserción para ajustar tu elemento componible diseños: modificadores de padding y modificadores de tamaño de inserción.

Modificadores de padding

Modifier.windowInsetsPadding(windowInsets: WindowInsets) aplica la las inserciones de ventana dadas como relleno, que actúan como lo haría Modifier.padding. Por ejemplo, Modifier.windowInsetsPadding(WindowInsets.safeDrawing) aplica las inserciones de dibujo seguras como relleno en los 4 lados.

También hay varios métodos de utilidad integrados para los tipos de inserción más comunes. Modifier.safeDrawingPadding() es uno de esos métodos, equivalente a Modifier.windowInsetsPadding(WindowInsets.safeDrawing) Hay ejemplos similares para los otros tipos de inserción.

Modificadores de tamaño de la inserción

Los siguientes modificadores aplican una cantidad de inserciones de ventana configurando el tamaño del componente para que sea el tamaño de las inserciones:

Modifier.windowInsetsStartWidth(windowInsets: WindowInsets)	Aplica el lado inicial de windowInsets como el ancho (como Modifier.width).
Modifier.windowInsetsEndWidth(windowInsets: WindowInsets)	Aplica el lado final de windowInsets como el ancho (como Modifier.width).
Modifier.windowInsetsTopHeight(windowInsets: WindowInsets)	Aplica el lado superior de windowInsets como la altura (como Modifier.height).
Modifier.windowInsetsBottomHeight(windowInsets: WindowInsets)	Aplica el lado inferior de windowInsets como la altura (como Modifier.height).

Estos modificadores son especialmente útiles para ajustar el tamaño de un Spacer que ocupa la espacio de inserciones:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

Inserción de consumo

Los modificadores de padding de inset (windowInsetsPadding y ayudantes como safeDrawingPadding) consumen automáticamente la parte de los insets que se aplican como padding. Mientras se profundiza en el árbol de composición, los modificadores de padding de inset anidados y los modificadores de tamaño de inset saben que algunos de los insets ya fueron consumidos por los modificadores de padding de inset externo y evitan usar la misma parte de los insets más de una vez, lo que generaría demasiado espacio adicional.

Los modificadores de tamaño de inserción también evitan usar la misma parte de las inserciones más de una vez si las inserciones ya se consumieron. Sin embargo, dado que están cambiando directamente, no consumen las inserciones por sí mismas.

Como resultado, los modificadores de padding anidados cambian automáticamente la cantidad de padding aplicado a cada elemento componible.

Si observas el mismo ejemplo de LazyColumn que antes, el modificador imePadding cambia el tamaño de LazyColumn. Dentro de LazyColumn, el último elemento tiene el tamaño de la altura de la parte inferior de las barras del sistema:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

Cuando se cierra el IME, el modificador imePadding() no aplica padding, ya que el IME no tiene altura. Como el modificador imePadding() no aplica padding, no se consumen inserciones, y la altura de Spacer será el tamaño de la parte inferior de las barras del sistema.

Cuando se abre el IME, las inserciones se animan para coincidir con el tamaño del IME, y El modificador imePadding() comienza a aplicar padding inferior para cambiar el tamaño LazyColumn cuando se abre el IME. Cuando se comienza a aplicar el modificador imePadding() con padding inferior, también comienza a consumir esa cantidad de inserciones. Por lo tanto, el la altura de Spacer comienza a disminuir, como parte del espaciado del sistema el modificador imePadding() ya aplicó las barras. Una vez que El modificador imePadding() aplica una cantidad de padding inferior más grande que las barras del sistema, la altura de Spacer es cero.

Cuando se cierra el IME, los cambios ocurren a la inversa: Spacer comienza a expandir desde una altura de cero cuando la imePadding() se aplique menos que la en la parte inferior de las barras del sistema. Por último, hasta que Spacer coincida con la altura de la parte inferior de las barras del sistema una vez que el IME esté completamente animado.

Figura 2: Columna diferida de borde a borde con TextField.

Precaución: Usa Spacer en lugar de contentPadding para dibujar el último TextField. en un LazyColumn por encima de las barras del sistema. De lo contrario, el IME puede ocultar el TextField.

Este comportamiento se logra a través de la comunicación entre todos los modificadores windowInsetsPadding y puede verse influenciado de otras maneras.

Modifier.consumeWindowInsets(insets: WindowInsets) también consume inserciones de la misma manera que Modifier.windowInsetsPadding, pero no se aplica las inserciones consumidas como relleno. Esto resulta útil en combinación con la inserción modificadores de tamaño, para indicar a los hermanos que tiene una cierta cantidad de inserciones ya se consumió:

Column(Modifier.verticalScroll(rememberScrollState())) {
    Spacer(Modifier.windowInsetsTopHeight(WindowInsets.systemBars))

    Column(
        Modifier.consumeWindowInsets(
            WindowInsets.systemBars.only(WindowInsetsSides.Vertical)
        )
    ) {
        // content
        Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
    }

    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.systemBars))
}
InsetsSnippets.kt

Modifier.consumeWindowInsets(paddingValues: PaddingValues) se comporta de forma muy de manera similar a la versión con un argumento WindowInsets, pero toma un PaddingValues arbitrario para consumir. Esto es útil para informar cuando el relleno o el espaciado lo proporciona algún otro mecanismo modificadores de padding de inserción, como un Modifier.padding común o una altura fija separadores:

Column(Modifier.padding(16.dp).consumeWindowInsets(PaddingValues(16.dp))) {
    // content
    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
}
InsetsSnippets.kt

En los casos en que se necesiten las inserciones de ventana sin procesar sin consumo, usa los valores de WindowInsets directamente o usa WindowInsets.asPaddingValues() para mostrar un PaddingValues de las inserciones que no se ven afectadas por el consumo. Sin embargo, debido a las advertencias que se indican a continuación, prefiere usar los modificadores de padding de inserciones de ventana y los modificadores de tamaño de inserciones de ventana siempre que sea posible.

Insets y fases de Jetpack Compose

Compose usa las APIs principales subyacentes de AndroidX para actualizar y animar los insertos, que usan las APIs de la plataforma subyacentes que administran los insertos. Debido a ese comportamiento de la plataforma, los insertos tienen una relación especial con las fases de Jetpack Compose.

El valor de las inserciones se actualiza después de la fase de composición, pero antes de la en la fase de diseño. Esto significa que, por lo general, leer el valor de las inserciones en la composición usa un valor de las inserciones que está un fotograma atrasado. El sistema integrado los modificadores descritos en esta página están diseñados para retrasar el uso de los valores de la inserciones hasta la fase de diseño, lo que garantiza que los valores de inserción se usen en en el mismo marco a medida que se actualizan.

Animaciones del IME del teclado con WindowInsets

Puedes aplicar Modifier.imeNestedScroll() a un contenedor de desplazamiento para abrir y cerrar el IME automáticamente cuando te desplazas hasta la parte inferior del contenedor.

class WindowInsetsExampleActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        WindowCompat.setDecorFitsSystemWindows(window, false)

        setContent {
            MaterialTheme {
                MyScreen()
            }
        }
    }
}

@OptIn(ExperimentalLayoutApi::class)
@Composable
fun MyScreen() {
    Box {
        LazyColumn(
            modifier = Modifier
                .fillMaxSize() // fill the entire window
                .imePadding() // padding for the bottom for the IME
                .imeNestedScroll(), // scroll IME at the bottom
            content = { }
        )
        FloatingActionButton(
            modifier = Modifier
                .align(Alignment.BottomEnd)
                .padding(16.dp) // normal 16dp of padding for FABs
                .navigationBarsPadding() // padding for navigation bar
                .imePadding(), // padding for when IME appears
            onClick = { }
        ) {
            Icon(imageVector = Icons.Filled.Add, contentDescription = "Add")
        }
    }
}
MigrationOtherConsiderationsSnippets.kt

Figura 3: Animaciones del IME

Compatibilidad con inserciones para componentes de Material 3

Para facilitar el uso, muchos de los elementos componibles integrados de Material 3 (androidx.compose.material3) controlan las inserciones por su cuenta, según la forma en que se colocan los elementos componibles en tu app según las especificaciones de Material.

Nota: Componentes de Material 2 (androidx.compose.material) no manejan automáticamente las inserciones. Sin embargo, puedes acceder a la inserciones y aplicarlas manualmente. En androidx.compose.material 1.6.0 y, luego, usa el parámetro windowInsets para aplicar las inserciones de forma manual para BottomAppBar, TopAppBar, BottomNavigation y NavigationRail. De la misma manera, usa el parámetro contentWindowInsets para Scaffold. De lo contrario, aplica las inserciones de forma manual como relleno.

Elementos componibles que manejan inserciones

A continuación, se incluye una lista de Material Componentes que controlar automáticamente las inserciones.

Barras de la app

• TopAppBar/ SmallTopAppBar/ CenterAlignedTopAppBar/ MediumTopAppBar/ LargeTopAppBar: Aplica los lados superior y horizontal de las barras del sistema como relleno, ya que se usa en la parte superior de la ventana.
• BottomAppBar: Aplica los lados inferior y horizontal de las barras del sistema como padding.

Contenedores de contenido

• ModalDrawerSheet / DismissibleDrawerSheet / PermanentDrawerSheet (contenido dentro de un panel lateral de navegación modal): Aplica inserciones verticales y de inicio al contenido.
• ModalBottomSheet: Aplica las inserciones inferiores.
• NavigationBar : Aplica las inserciones inferior y horizontal.
• NavigationRail: Aplica las inserciones vertical y inicio.

Scaffold

De forma predeterminada, Scaffold proporciona inserciones como el parámetro paddingValues para que las consumas y las uses. Scaffold no aplica los inserciones al contenido; esta responsabilidad es tuya. Por ejemplo, para consumir estas inserciones con un LazyColumn dentro de un Scaffold:

Scaffold { innerPadding ->
    // innerPadding contains inset information for you to use and apply
    LazyColumn(
        // consume insets as scaffold doesn't do it by default
        modifier = Modifier.consumeWindowInsets(innerPadding),
        contentPadding = innerPadding
    ) {
        items(count = 100) {
            Box(
                Modifier
                    .fillMaxWidth()
                    .height(50.dp)
                    .background(colors[it % colors.size])
            )
        }
    }
}
InsetsSnippets.kt

Anula las inserciones predeterminadas

Puedes cambiar el parámetro windowInsets que se pasa al elemento componible para configurar su comportamiento. Este parámetro puede ser un tipo diferente de la inserción de ventana para aplicar en su lugar, o la inhabilitación pasa una instancia vacía: WindowInsets(0, 0, 0, 0)

Por ejemplo, para inhabilitar el manejo de inserciones en LargeTopAppBar, Configura el parámetro windowInsets en una instancia vacía:

LargeTopAppBar(
    windowInsets = WindowInsets(0, 0, 0, 0),
    title = {
        Text("Hi")
    }
)
InsetsSnippets.kt

Interoperabilidad con las inserciones del sistema de View

Es posible que debas anular los rellenos predeterminados cuando tu pantalla tenga elementos View y código de Compose en la misma jerarquía. En este caso, debes ser explícito en cuál debe consumir los insertos y cuál debe ignorarlos.

Por ejemplo, si tu diseño más externo es un diseño de View de Android, debes consumir los inserciones en el sistema de View y, luego, ignorarlas para Compose. Como alternativa, si tu diseño más externo es un elemento componible, debes consumir los inserciones en Compose y rellenar los elementos componibles AndroidView según corresponda.

De forma predeterminada, cada ComposeView consume todas las inserciones en el WindowInsetsCompat nivel de consumo. Para cambiar este comportamiento predeterminado, establece ComposeView.consumeWindowInsets en false.

Recursos

• Now in Android: Es una app para Android completamente funcional compilada por completo con Kotlin y Jetpack Compose.
• Controla las aplicaciones de borde a borde en Android 15: Un codelab en el que se explica la aplicación de borde a borde de Android 15.
• Sugerencias para controlar los márgenes de Android 15
• Obtén una vista previa y prueba la IU de borde a borde de tu app
• 3 aspectos para mejorar la experiencia de tu app para Android: Borde a borde, Atrás predictivo y Vista rápida: un video de YouTube sobre la aplicación forzosa de borde a borde en Android 15
• Edge-to-edge and insets | Compose Tips: Un video de YouTube en el que se muestra cómo controlar los elementos insertados para dibujar de borde a borde.