Configura inserciones de ventana

Para permitir que tu app tenga control total sobre dónde dibuja el contenido, sigue estos pasos de configuración. Sin estos pasos, es posible que tu app dibuje colores negros o sólidos detrás de la IU del sistema, o que no se anime de forma síncrona con el teclado en software.

1. Orienta tu app a Android 15 (nivel de API 35) o versiones posteriores para aplicar el diseño de pantalla completa en Android 15 y versiones posteriores. Tu app se muestra detrás de la IU del sistema. Puedes controlar las inserciones para ajustar la IU de tu app.
2. De manera opcional, llama a enableEdgeToEdge() en Activity.onCreate(), lo que permite que tu app sea de borde a borde en versiones anteriores 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, lo que te ayuda a aplicar el diseño y el padding adecuados 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">
   

Usa las APIs de Compose

Una vez que tu actividad haya tomado el control de la administración de todos los insertos, puedes usar las APIs de Compose para asegurarte de que el contenido no se oculte y que los elementos interactivos no se superpongan con la IU del sistema. Estas APIs también sincronizan el diseño de tu app con los cambios de insert.

Por ejemplo, este es el método más básico para aplicar los insertos al contenido de toda tu 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 relleno alrededor del contenido completo de la app. Si bien esto garantiza que los elementos interactivos no se superpongan con la IU del sistema, también significa que nada de la app se dibujará detrás de la IU del sistema para lograr un efecto de borde a borde. Para aprovechar al máximo la ventana, debes ajustar dónde se aplican las inserciones en cada pantalla o componente.

Todos estos tipos de inserciones se animan automáticamente con animaciones del IME que se retroportaron a la API 21. Por extensión, todos tus diseños que usan estos rellenos también se animan automáticamente a medida que cambian los valores de relleno.

Existen dos formas principales de usar estos tipos de inserciones para ajustar tus diseños componibles: modificadores de padding y modificadores de tamaño de inserción.

Modificadores de padding

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

También hay varios métodos de utilidad integrados para los tipos de inserciones más comunes. Modifier.safeDrawingPadding() es uno de esos métodos, equivalente a Modifier.windowInsetsPadding(WindowInsets.safeDrawing). Existen modificadores análogos para los otros tipos de inserciones.

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:

Estos modificadores son particularmente útiles para ajustar el tamaño de un Spacer que ocupa el espacio de los elementos intercalados:

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

Consumo de intercalación

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 externos 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 inserciones también evitan usar la misma parte de inserciones más de una vez si ya se consumieron. Sin embargo, como cambian su tamaño directamente, no consumen inserciones.

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 el IME está cerrado, el modificador imePadding() no aplica padding, ya que el IME no tiene altura. Como el modificador imePadding() no aplica relleno, no se consumen inserciones, y la altura de Spacer será del tamaño del lado inferior de las barras del sistema.

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

Cuando se cierra el IME, los cambios se producen a la inversa: Spacer comienza a expandirse desde una altura de cero una vez que imePadding() aplica menos que el lado inferior de las barras del sistema, hasta que finalmente Spacer coincide con la altura del lado inferior de las barras del sistema una vez que el IME se anima por completo.

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 aplica las inserciones consumidas como padding. Esto es útil en combinación con los modificadores de tamaño de los rellenos para indicar a los elementos hermanos que ya se consumió una cantidad determinada de rellenos:

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 manera muy similar a la versión con un argumento WindowInsets, pero toma un PaddingValues arbitrario para consumir. Esto es útil para informar a los elementos secundarios cuando el padding o el espaciado se proporcionan a través de algún otro mecanismo que no sean los modificadores de padding intercalado, como un Modifier.padding ordinario o espaciadores de altura fija:

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 siguientes advertencias, prefiere usar los modificadores de padding de los márgenes de la ventana y los modificadores de tamaño de los márgenes de la 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 los rellenos se actualiza después de la fase de composición, pero antes de 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. Los modificadores integrados que se describen en esta página se compilan para retrasar el uso de los valores de los rellenos hasta la fase de diseño, lo que garantiza que los valores de relleno se usen en el mismo marco a medida que se actualizan.