Animationsmodifikatoren und zusammensetzbare Funktionen

Compose bietet integrierte Composables und Modifikatoren für gängige Animationsanwendungsfälle.

Integrierte animierte Composables

Compose bietet mehrere Composables, mit denen das Erscheinen, Verschwinden und Layoutänderungen von Inhalten animiert werden können.

Ein- und Ausblenden animieren

Abbildung 1. Ein- und Ausblenden eines Elements in einer Spalte animieren

Das Compose-Element AnimatedVisibility animiert das Ein- und Ausblenden seines Inhalts.

var visible by remember {
    mutableStateOf(true)
}
// Animated visibility will eventually remove the item from the composition once the animation has finished.
AnimatedVisibility(visible) {
    // your composable here
    // ...
}
AnimationQuickGuide.kt

Standardmäßig wird der Inhalt durch Einblenden und Erweitern angezeigt und durch Ausblenden und Verkleinern ausgeblendet. Sie können diesen Übergang anpassen, indem Sie die Objekte EnterTransition und ExitTransition angeben.

var visible by remember { mutableStateOf(true) }
val density = LocalDensity.current
AnimatedVisibility(
    visible = visible,
    enter = slideInVertically {
        // Slide in from 40 dp from the top.
        with(density) { -40.dp.roundToPx() }
    } + expandVertically(
        // Expand from the top.
        expandFrom = Alignment.Top
    ) + fadeIn(
        // Fade in with the initial alpha of 0.3f.
        initialAlpha = 0.3f
    ),
    exit = slideOutVertically() + shrinkVertically() + fadeOut()
) {
    Text(
        "Hello",
        Modifier
            .fillMaxWidth()
            .height(200.dp)
    )
}
AnimationSnippets.kt

Wie im vorherigen Beispiel gezeigt, können Sie mehrere EnterTransition- oder ExitTransition-Objekte mit einem +-Operator kombinieren. Jedes Objekt akzeptiert optionale Parameter, um das Verhalten anzupassen. Weitere Informationen finden Sie auf den Referenzseiten.

Beispiele für Übergänge beim Ein- und Ausblenden

EnterTransition	ExitTransition
fadeIn	fadeOut
slideIn	slideOut
slideInHorizontally	slideOutHorizontally
slideInVertically	slideOutVertically
scaleIn	scaleOut
expandIn	shrinkOut
expandHorizontally	shrinkHorizontally
expandVertically	shrinkVertically

AnimatedVisibility bietet auch eine Variante, die ein MutableTransitionState-Argument akzeptiert. So können Sie eine Animation auslösen, sobald die AnimatedVisibility komponierbare Funktion dem Kompositionsbaum hinzugefügt wird. Außerdem ist sie nützlich, um den Animationsstatus zu beobachten.

// Create a MutableTransitionState<Boolean> for the AnimatedVisibility.
val state = remember {
    MutableTransitionState(false).apply {
        // Start the animation immediately.
        targetState = true
    }
}
Column {
    AnimatedVisibility(visibleState = state) {
        Text(text = "Hello, world!")
    }

    // Use the MutableTransitionState to know the current animation state
    // of the AnimatedVisibility.
    Text(
        text = when {
            state.isIdle && state.currentState -> "Visible"
            !state.isIdle && state.currentState -> "Disappearing"
            state.isIdle && !state.currentState -> "Invisible"
            else -> "Appearing"
        }
    )
}
AnimationSnippets.kt

Ein- und Ausblenden für untergeordnete Elemente animieren

Inhalte innerhalb von AnimatedVisibility (direkte oder indirekte untergeordnete Elemente) können den Modifikator animateEnterExit verwenden, um für jedes Element ein anderes Animationsverhalten anzugeben. Der visuelle Effekt für jedes dieser untergeordneten Elemente ist eine Kombination aus den Animationen, die im AnimatedVisibility-Composable angegeben sind, und den eigenen Ein- und Ausblendanimationen des untergeordneten Elements.

var visible by remember { mutableStateOf(true) }

AnimatedVisibility(
    visible = visible,
    enter = fadeIn(),
    exit = fadeOut()
) {
    // Fade in/out the background and the foreground.
    Box(
        Modifier
            .fillMaxSize()
            .background(Color.DarkGray)
    ) {
        Box(
            Modifier
                .align(Alignment.Center)
                .animateEnterExit(
                    // Slide in/out the inner box.
                    enter = slideInVertically(),
                    exit = slideOutVertically()
                )
                .sizeIn(minWidth = 256.dp, minHeight = 64.dp)
                .background(Color.Red)
        ) {
            // Content of the notification…
        }
    }
}
AnimationSnippets.kt

In einigen Fällen möchten Sie möglicherweise, dass AnimatedVisibility überhaupt keine Animationen anwendet, damit jedes untergeordnete Element eine eigene Animation von animateEnterExit haben kann. Geben Sie dazu EnterTransition.None und ExitTransition.None in der komponierbaren Funktion AnimatedVisibility an.

Benutzerdefinierte Animation hinzufügen

Wenn Sie benutzerdefinierte Animationseffekte hinzufügen möchten, die über die integrierten Ein- und Ausblendanimationen hinausgehen, greifen Sie mit der Property transition im Content-Lambda für AnimatedVisibility auf die zugrunde liegende Transition-Instanz zu. Alle Animationsstatus, die der Übergangsinstanz hinzugefügt werden, werden gleichzeitig mit den Ein- und Ausblendanimationen von AnimatedVisibility ausgeführt. AnimatedVisibility wartet, bis alle Animationen in Transition abgeschlossen sind, bevor der Inhalt entfernt wird. Bei Exit-Animationen, die unabhängig von Transition erstellt wurden (z. B. mit animate*AsState), kann AnimatedVisibility sie nicht berücksichtigen und entfernt daher möglicherweise das Content-Composable, bevor sie abgeschlossen sind.

var visible by remember { mutableStateOf(true) }

AnimatedVisibility(
    visible = visible,
    enter = fadeIn(),
    exit = fadeOut()
) { // this: AnimatedVisibilityScope
    // Use AnimatedVisibilityScope#transition to add a custom animation
    // to the AnimatedVisibility.
    val background by transition.animateColor(label = "color") { state ->
        if (state == EnterExitState.Visible) Color.Blue else Color.Gray
    }
    Box(
        modifier = Modifier
            .size(128.dp)
            .background(background)
    )
}
AnimationSnippets.kt

Weitere Informationen zur Verwendung von Transition zum Verwalten von Animationen finden Sie unter Mehrere Attribute gleichzeitig mit einem Übergang animieren.

Animation basierend auf dem Zielzustand

Das AnimatedContent komponierbare Element animiert seinen Inhalt, wenn er sich basierend auf einem Zielzustand ändert.

Row {
    var count by remember { mutableIntStateOf(0) }
    Button(onClick = { count++ }) {
        Text("Add")
    }
    AnimatedContent(
        targetState = count,
        label = "animated content"
    ) { targetCount ->
        // Make sure to use `targetCount`, not `count`.
        Text(text = "Count: $targetCount")
    }
}
AnimationSnippets.kt

Hinweis: Sie müssen immer den Lambda-Parameter verwenden und ihn im Inhalt widerspiegeln. Die API verwendet diesen Wert als Schlüssel, um den aktuell angezeigten Inhalt zu identifizieren.

Standardmäßig wird der ursprüngliche Inhalt ausgeblendet und dann der Zielinhalt eingeblendet (dieses Verhalten wird als Überblenden bezeichnet). Sie können dieses Animationsverhalten anpassen, indem Sie ein ContentTransform-Objekt für den Parameter transitionSpec angeben. Sie können eine Instanz von ContentTransform erstellen, indem Sie ein EnterTransition-Objekt mit einem ExitTransition-Objekt mithilfe der Infix-Funktion with kombinieren. Sie können SizeTransform auf das ContentTransform-Objekt anwenden, indem Sie es mit der Infix-Funktion using anhängen.

AnimatedContent(
    targetState = count,
    transitionSpec = {
        // Compare the incoming number with the previous number.
        if (targetState > initialState) {
            // If the target number is larger, it slides up and fades in
            // while the initial (smaller) number slides up and fades out.
            slideInVertically { height -> height } + fadeIn() togetherWith
                slideOutVertically { height -> -height } + fadeOut()
        } else {
            // If the target number is smaller, it slides down and fades in
            // while the initial number slides down and fades out.
            slideInVertically { height -> -height } + fadeIn() togetherWith
                slideOutVertically { height -> height } + fadeOut()
        }.using(
            // Disable clipping since the faded slide-in/out should
            // be displayed out of bounds.
            SizeTransform(clip = false)
        )
    }, label = "animated content"
) { targetCount ->
    Text(text = "$targetCount")
}
AnimationSnippets.kt

EnterTransition definiert, wie der Zielinhalt angezeigt werden soll, und ExitTransition definiert, wie der ursprüngliche Inhalt ausgeblendet werden soll. Zusätzlich zu allen EnterTransition- und ExitTransition-Funktionen, die für AnimatedVisibility verfügbar sind, bietet AnimatedContent slideIntoContainer und slideOutOfContainer. Dies sind praktische Alternativen zu slideInHorizontally/Vertically und slideOutHorizontally/Vertically, die die Verschiebedistanz basierend auf der Größe des ursprünglichen Inhalts und des Zielinhalts des AnimatedContent-Inhalts berechnen.

SizeTransform definiert, wie die Größe zwischen dem ursprünglichen und dem Zielinhalt animiert werden soll. Beim Erstellen der Animation haben Sie Zugriff sowohl auf die ursprüngliche Größe als auch auf die Zielgröße. SizeTransform steuert auch, ob der Inhalt während Animationen auf die Komponentengröße zugeschnitten werden soll.

var expanded by remember { mutableStateOf(false) }
Surface(
    color = MaterialTheme.colorScheme.primary,
    onClick = { expanded = !expanded }
) {
    AnimatedContent(
        targetState = expanded,
        transitionSpec = {
            fadeIn(animationSpec = tween(150, 150)) togetherWith
                fadeOut(animationSpec = tween(150)) using
                SizeTransform { initialSize, targetSize ->
                    if (targetState) {
                        keyframes {
                            // Expand horizontally first.
                            IntSize(targetSize.width, initialSize.height) at 150
                            durationMillis = 300
                        }
                    } else {
                        keyframes {
                            // Shrink vertically first.
                            IntSize(initialSize.width, targetSize.height) at 150
                            durationMillis = 300
                        }
                    }
                }
        }, label = "size transform"
    ) { targetExpanded ->
        if (targetExpanded) {
            Expanded()
        } else {
            ContentIcon()
        }
    }
}
AnimationSnippets.kt

Übergänge beim Ein- und Ausblenden von untergeordneten Elementen animieren

Wie bei AnimatedVisibility ist der Modifikator animateEnterExit im Content-Lambda von AnimatedContent verfügbar. Verwenden Sie diese Option, um EnterAnimation und ExitAnimation auf jedes der direkten oder indirekten untergeordneten Elemente separat anzuwenden.

Benutzerdefinierte Animation hinzufügen

Genau wie AnimatedVisibility ist das Feld transition im Content-Lambda von AnimatedContent verfügbar. Damit können Sie einen benutzerdefinierten Animationseffekt erstellen, der gleichzeitig mit dem Übergang AnimatedContent ausgeführt wird. Weitere Informationen findest du unter updateTransition.

Animation zwischen zwei Layouts

Crossfade animiert den Übergang zwischen zwei Layouts mit einer Überblendungsanimation. Durch Umschalten des an den Parameter current übergebenen Werts wird der Inhalt mit einer Überblendungsanimation gewechselt.

var currentPage by remember { mutableStateOf("A") }
Crossfade(targetState = currentPage, label = "cross fade") { screen ->
    when (screen) {
        "A" -> Text("Page A")
        "B" -> Text("Page B")
    }
}
AnimationSnippets.kt

Integrierte Animationsmodifikatoren

Compose bietet Modifikatoren, mit denen bestimmte Änderungen direkt in Composables animiert werden können.

Größenänderungen von Compose-Elementen animieren

Abbildung 2: Composable, das flüssig zwischen einer kleinen und einer größeren Größe animiert wird

Der Modifikator animateContentSize animiert eine Größenänderung.

Hinweis: Die Reihenfolge, in der animateContentSize in der Modifikatorkette platziert wird, ist wichtig. Für flüssige Animationen platzieren Sie ihn vor allen Größenmodifikatoren wie size oder defaultMinSize, damit animateContentSize die animierte Wertänderung an das Layout meldet.

var expanded by remember { mutableStateOf(false) }
Box(
    modifier = Modifier
        .background(colorBlue)
        .animateContentSize()
        .height(if (expanded) 400.dp else 200.dp)
        .fillMaxWidth()
        .clickable(
            interactionSource = remember { MutableInteractionSource() },
            indication = null
        ) {
            expanded = !expanded
        }

) {
}
AnimationQuickGuide.kt

Animationen für Listenelemente

Wenn Sie die Neuanordnung von Elementen in einer Lazy List oder einem Lazy Grid animieren möchten, lesen Sie die Dokumentation zur Animation von Lazy-Layout-Elementen.