Configura inserciones de ventana

Una vez que tu actividad haya tomado el control de todos los elementos de inserción, podrás usar las APIs de Compose para verificar que el contenido no esté oculto 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 inserción.

Controla las inserciones con modificadores de padding o tamaño

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

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

    enableEdgeToEdge()

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

Este fragmento aplica las inserciones de ventana safeDrawing como padding alrededor de todo el contenido de la app. Si bien esto garantiza que los elementos interactivos no se superpongan con la IU del sistema, también significa que ninguna parte 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 toda la ventana, debes ajustar con precisión dónde se aplican las inserciones en cada pantalla o componente.

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

Existen tres maneras de controlar las inserciones para ajustar tus diseños de elementos componibles:

Modificadores de padding

Modifier.windowInsetsPadding(windowInsets: WindowInsets) aplica las inserciones de ventana dadas como padding, de la misma manera que lo haría Modifier.padding. Por ejemplo, Modifier.windowInsetsPadding(WindowInsets.safeDrawing) aplica las inserciones de dibujo seguras como padding 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). En la siguiente tabla, se enumeran los modificadores de padding integrados y el tipo de WindowInsets que aplica cada uno:

Modifier.safeDrawingPadding()

WindowInsets.safeDrawing

Modifier.safeGesturesPadding()

WindowInsets.safeGestures

Modifier.safeContentPadding()

WindowInsets.safeContent

Modifier.statusBarsPadding()

WindowInsets.statusBars

Modifier.navigationBarsPadding()

WindowInsets.navigationBars

Modifier.captionBarPadding()

WindowInsets.captionBar

Modifier.systemBarsPadding()

WindowInsets.systemBars

Modifier.imePadding()

WindowInsets.ime

Modifier.systemGesturesPadding()

WindowInsets.systemGestures

Modifier.mandatorySystemGesturesPadding()

WindowInsets.mandatorySystemGestures

Modifier.displayCutoutPadding()

WindowInsets.displayCutout

Modifier.waterfallPadding()

WindowInsets.waterfall

Para saber qué cubre cada tipo de inserción, consulta Acerca de las inserciones de ventanas.

Modificadores de tamaño de inserción

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

Modifier.windowInsetsStartWidth(windowInsets: WindowInsets)

Aplica el lado de inicio 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 el espacio de las inserciones:

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

Consumo de inserciones

Los modificadores de padding de inserción (windowInsetsPadding y ayudantes como safeDrawingPadding) consumen automáticamente la parte de las inserciones que se aplican como padding. A medida que se profundiza en el árbol de composición, los modificadores de padding de inserción anidados y los modificadores de tamaño de inserción saben que los modificadores de padding de inserción externos ya consumieron una parte de las inserciones y evitan usar la misma parte de las inserciones 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 ya se consumieron. Sin embargo, como cambian su tamaño directamente, no consumen inserciones por sí mismos.

Como resultado, los modificadores de padding anidados cambian automáticamente la cantidad de padding que se aplica 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
            )
        )
    }
}

Cuando se cierra el IME, imePadding() no aplica ningún padding. En consecuencia, no se consumen inserciones y la altura de Spacer coincide con las barras del sistema inferiores.

Cuando se abre el IME, las inserciones del IME se animan para que coincidan con el tamaño del IME, y el modificador imePadding() comienza a aplicar un padding inferior para cambiar el tamaño de LazyColumn a medida que se abre el IME. A medida que el modificador imePadding() comienza a aplicar el padding inferior, también empieza 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 de las barras del sistema. Una vez que el modificador imePadding() aplica una cantidad de padding inferior 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 se expande desde la altura cero, ya que imePadding() aplica menos que las barras del sistema inferiores. Por último, la altura de Spacer coincide con las barras del sistema una vez que la animación del IME finaliza por completo.

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

Este comportamiento se logra a través de la comunicación entre todos los modificadores windowInsetsPadding y se puede influenciar 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 inserción para indicar a los elementos hermanos que ya se consumió una cierta cantidad de inserciones:

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))
}

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 algún otro mecanismo que no sean los modificadores de padding de inserción proporciona padding o espaciado, como un Modifier.padding común o espaciadores de altura fija:

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

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

Las inserciones y las fases de Jetpack Compose

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

El valor de los elementos de inserción se actualiza después de la fase de composición, pero antes de la fase de diseño. Esto significa que, para leer el valor de las inserciones en la composición, generalmente se usa un valor de las inserciones que tiene un fotograma de retraso. Los modificadores integrados que se describen en esta página se crearon para retrasar el uso de los valores de las inserciones hasta la fase de diseño, lo que garantiza que los valores de inserción se usen en el mismo fotograma en el que se actualizan.

Anterior
Información acerca de las inserciones de ventana
Siguiente
Cómo usar animaciones del IME del teclado