אנימציות מבוססות-ערך

בדף הזה נסביר איך ליצור אנימציות מבוססות-ערך ב-Jetpack Compose, תוך התמקדות בממשקי API שמנפישים ערכים על סמך המצבים הנוכחיים והמצבים של היעד.

יצירת אנימציה של ערך יחיד באמצעות animate*AsState

הפונקציות animate*AsState הן ממשקי API פשוטים לאנימציה ב-Compose, שמאפשרים להנפיש ערך יחיד. אתם מספקים רק את ערך היעד (או ערך הסיום), וה-API מתחיל את האנימציה מהערך הנוכחי לערך שצוין.

בדוגמה הבאה מוצגת אנימציה של אלפא באמצעות ה-API הזה. אם עוטפים את ערך היעד ב-animateFloatAsState, ערך האלפא הופך לערך אנימציה בין הערכים שצוינו (1f או 0.5f במקרה הזה).

var enabled by remember { mutableStateOf(true) }

val animatedAlpha: Float by animateFloatAsState(if (enabled) 1f else 0.5f, label = "alpha")
Box(
    Modifier
        .fillMaxSize()
        .graphicsLayer { alpha = animatedAlpha }
        .background(Color.Red)
)
AnimationSnippets.kt

אין צורך ליצור מופע של מחלקת אנימציה או לטפל בהפרעה. מתחת לפני השטח, נוצר אובייקט אנימציה (כלומר, מופע) והוא נשמר באתר הקריאה, כשהערך הראשון של היעד הוא הערך ההתחלתי שלו.Animatable מכאן ואילך, בכל פעם שתספקו לרכיב הזה ערך יעד שונה, אנימציה תתחיל באופן אוטומטי לכיוון הערך הזה. אם כבר יש אנימציה שפועלת, האנימציה מתחילה מהערך הנוכחי שלה (והמהירות שלה) ופועלת לכיוון ערך היעד. במהלך האנימציה, הקומפוזיציה הזו מורכבת מחדש ומחזירה ערך אנימציה מעודכן בכל פריים.

כברירת מחדל, ב-Compose יש animate*AsState פונקציות ל-Float,‏ Color,‏ Dp,‏ Size,‏ Offset,‏ Rect,‏ Int,‏ IntOffset ו-IntSize. אפשר להוסיף תמיכה בסוגי נתונים אחרים על ידי מתן TwoWayConverter ל-animateValueAsState שמקבל סוג כללי.

אפשר להתאים אישית את מפרטי האנימציה על ידי ציון AnimationSpec. מידע נוסף זמין בכתובת AnimationSpec.

הנפשה של כמה מאפיינים בו-זמנית באמצעות מעבר

‫Transition מנהל אנימציה אחת או יותר כרכיבי צאצא ומפעיל אותן בו-זמנית בין כמה מצבים.

המצבים יכולים להיות מכל סוג נתונים. במקרים רבים, אפשר להשתמש בenum סוג מותאם אישית כדי לאמת את בטיחות הסוג, כמו בדוגמה הזו:

enum class BoxState {
    Collapsed,
    Expanded
}
AnimationSnippets.kt

‫updateTransition יוצרת וזוכרת מופע של Transition ומעדכנת את המצב שלו.

var currentState by remember { mutableStateOf(BoxState.Collapsed) }
val transition = updateTransition(currentState, label = "box state")
AnimationSnippets.kt

לאחר מכן תוכלו להשתמש באחת מפונקציות ההרחבה animate* כדי להגדיר אנימציה של רכיב צאצא במעבר הזה. מציינים את ערכי היעד לכל אחד מהמצבים. הפונקציות האלה animate* מחזירות ערך של אנימציה שמתעדכן בכל פריים במהלך האנימציה, כשהמצב של המעבר מתעדכן באמצעות updateTransition.

val rect by transition.animateRect(label = "rectangle") { state ->
    when (state) {
        BoxState.Collapsed -> Rect(0f, 0f, 100f, 100f)
        BoxState.Expanded -> Rect(100f, 100f, 300f, 300f)
    }
}
val borderWidth by transition.animateDp(label = "border width") { state ->
    when (state) {
        BoxState.Collapsed -> 1.dp
        BoxState.Expanded -> 0.dp
    }
}
AnimationSnippets.kt

אפשר להעביר פרמטר transitionSpec כדי לציין AnimationSpec שונה לכל אחת מהקומבינציות של שינויים במצב המעבר. מידע נוסף זמין במאמר AnimationSpec.

val color by transition.animateColor(
    transitionSpec = {
        when {
            BoxState.Expanded isTransitioningTo BoxState.Collapsed ->
                spring(stiffness = 50f)

            else ->
                tween(durationMillis = 500)
        }
    }, label = "color"
) { state ->
    when (state) {
        BoxState.Collapsed -> MaterialTheme.colorScheme.primary
        BoxState.Expanded -> MaterialTheme.colorScheme.background
    }
}
AnimationSnippets.kt

אחרי שהמעבר מגיע למצב היעד, Transition.currentState זהה ל-Transition.targetState. אפשר להשתמש בזה כאינדיקטור לכך שהמעבר הסתיים.

לפעמים, יכול להיות שתרצו להגדיר מצב התחלתי ששונה ממצב היעד הראשון. אפשר להשתמש ב-updateTransition עם MutableTransitionState כדי להשיג את זה. לדוגמה, אפשר להשתמש בו כדי להתחיל אנימציה ברגע שהקוד נכנס לקומפוזיציה.

// Start in collapsed state and immediately animate to expanded
var currentState = remember { MutableTransitionState(BoxState.Collapsed) }
currentState.targetState = BoxState.Expanded
val transition = rememberTransition(currentState, label = "box state")
// ……
AnimationSnippets.kt

למעבר מורכב יותר שכולל כמה פונקציות קומפוזביליות, אפשר להשתמש ב-createChildTransition כדי ליצור מעבר צאצא. הטכניקה הזו שימושית להפרדה בין בעיות בכמה רכיבי משנה ב-composable מורכב. אנימציות המעבר ברכיב האב מודעות לכל ערכי האנימציה במעברי הרכיבים הצאצאים.

enum class DialerState { DialerMinimized, NumberPad }

@Composable
fun DialerButton(isVisibleTransition: Transition<Boolean>) {
    // `isVisibleTransition` spares the need for the content to know
    // about other DialerStates. Instead, the content can focus on
    // animating the state change between visible and not visible.
}

@Composable
fun NumberPad(isVisibleTransition: Transition<Boolean>) {
    // `isVisibleTransition` spares the need for the content to know
    // about other DialerStates. Instead, the content can focus on
    // animating the state change between visible and not visible.
}

@Composable
fun Dialer(dialerState: DialerState) {
    val transition = updateTransition(dialerState, label = "dialer state")
    Box {
        // Creates separate child transitions of Boolean type for NumberPad
        // and DialerButton for any content animation between visible and
        // not visible
        NumberPad(
            transition.createChildTransition {
                it == DialerState.NumberPad
            }
        )
        DialerButton(
            transition.createChildTransition {
                it == DialerState.DialerMinimized
            }
        )
    }
}
AnimationSnippets.kt

שימוש במעבר עם AnimatedVisibility ו-AnimatedContent

‫AnimatedVisibility ו-AnimatedContent זמינים כפונקציות של תוסף Transition. הערך של targetState עבור Transition.AnimatedVisibility ו-Transition.AnimatedContent נגזר מ-Transition, ומפעיל אנימציות של כניסה, יציאה ו-sizeTransform לפי הצורך כש-targetState של Transition משתנה. פונקציות ההרחבה האלה מאפשרות להעביר את כל האנימציות של enter,‏ exit ו-sizeTransform, שאחרת היו פנימיות ל-AnimatedVisibility/AnimatedContent, אל Transition. בעזרת הפונקציות האלה של התוסף, אפשר לראות את השינוי במצב של AnimatedVisibility/AnimatedContent מבחוץ. במקום פרמטר בוליאני visible, הגרסה הזו של AnimatedVisibility מקבלת ביטוי למדא שממיר את מצב היעד של מעבר ההורה למצב בוליאני.

פרטים נוספים מופיעים במאמרים בנושא AnimatedVisibility וAnimatedContent.

var selected by remember { mutableStateOf(false) }
// Animates changes when `selected` is changed.
val transition = updateTransition(selected, label = "selected state")
val borderColor by transition.animateColor(label = "border color") { isSelected ->
    if (isSelected) Color.Magenta else Color.White
}
val elevation by transition.animateDp(label = "elevation") { isSelected ->
    if (isSelected) 10.dp else 2.dp
}
Surface(
    onClick = { selected = !selected },
    shape = RoundedCornerShape(8.dp),
    border = BorderStroke(2.dp, borderColor),
    shadowElevation = elevation
) {
    Column(
        modifier = Modifier
            .fillMaxWidth()
            .padding(16.dp)
    ) {
        Text(text = "Hello, world!")
        // AnimatedVisibility as a part of the transition.
        transition.AnimatedVisibility(
            visible = { targetSelected -> targetSelected },
            enter = expandVertically(),
            exit = shrinkVertically()
        ) {
            Text(text = "It is fine today.")
        }
        // AnimatedContent as a part of the transition.
        transition.AnimatedContent { targetState ->
            if (targetState) {
                Text(text = "Selected")
            } else {
                Icon(imageVector = Icons.Default.Phone, contentDescription = "Phone")
            }
        }
    }
}
AnimationSnippets.kt

איך יוצרים מעבר שאפשר להשתמש בו שוב

במקרים פשוטים, אפשר להגדיר אנימציות מעבר באותו קומפוזיציה של ממשק המשתמש. עם זאת, כשעובדים על רכיב מורכב עם מספר ערכים מונפשים, יכול להיות שתרצו להפריד את הטמעת האנימציה מממשק המשתמש שניתן להרכבה.

כדי לעשות זאת, יוצרים מחלקה שמכילה את כל ערכי האנימציה ופונקציה update שמחזירה מופע של המחלקה הזו. אפשר לחלץ את ההטמעה של המעבר לפונקציה נפרדת חדשה. הדפוס הזה שימושי כשצריך לרכז את לוגיקת האנימציה או ליצור אנימציות מורכבות שאפשר לעשות בהן שימוש חוזר.

enum class BoxState { Collapsed, Expanded }

@Composable
fun AnimatingBox(boxState: BoxState) {
    val transitionData = updateTransitionData(boxState)
    // UI tree
    Box(
        modifier = Modifier
            .background(transitionData.color)
            .size(transitionData.size)
    )
}

// Holds the animation values.
private class TransitionData(
    color: State<Color>,
    size: State<Dp>
) {
    val color by color
    val size by size
}

// Create a Transition and return its animation values.
@Composable
private fun updateTransitionData(boxState: BoxState): TransitionData {
    val transition = updateTransition(boxState, label = "box state")
    val color = transition.animateColor(label = "color") { state ->
        when (state) {
            BoxState.Collapsed -> Color.Gray
            BoxState.Expanded -> Color.Red
        }
    }
    val size = transition.animateDp(label = "size") { state ->
        when (state) {
            BoxState.Collapsed -> 64.dp
            BoxState.Expanded -> 128.dp
        }
    }
    return remember(transition) { TransitionData(color, size) }
}
AnimationSnippets.kt

יצירת אנימציה שחוזרת על עצמה ללא הפסקה באמצעות rememberInfiniteTransition

‫InfiniteTransition מכיל אנימציה אחת או יותר של ילדים כמו Transition, אבל האנימציות מתחילות לפעול ברגע שהן נכנסות לקומפוזיציה ולא מפסיקות אלא אם מסירים אותן. אפשר ליצור מופע של InfiniteTransition עם rememberInfiniteTransition, ולהוסיף אנימציות צאצא עם animateColor, animatedFloat או animatedValue. צריך גם לציין infiniteRepeatable כדי להגדיר את המפרט של האנימציה.

val infiniteTransition = rememberInfiniteTransition(label = "infinite")
val color by infiniteTransition.animateColor(
    initialValue = Color.Red,
    targetValue = Color.Green,
    animationSpec = infiniteRepeatable(
        animation = tween(1000, easing = LinearEasing),
        repeatMode = RepeatMode.Reverse
    ),
    label = "color"
)

Box(
    Modifier
        .fillMaxSize()
        .background(color)
)
AnimationSnippets.kt

ממשקי API של אנימציות ברמה נמוכה

כל ממשקי ה-API של האנימציה ברמה הגבוהה שצוינו בקטע הקודם מבוססים על ממשקי ה-API של האנימציה ברמה הנמוכה.

הפונקציות animate*AsState הן ממשקי API פשוטים שמציגים שינוי מיידי בערך כערך אנימציה. הפונקציונליות הזו נתמכת על ידי Animatable, API מבוסס-קורוטינות להנפשת ערך יחיד.

‫updateTransition יוצר אובייקט מעבר שיכול לנהל כמה ערכים של אנימציה ולהפעיל אותם כשמצב משתנה. ‫rememberInfiniteTransition דומה, אבל הוא יוצר מעבר אינסופי שיכול לנהל כמה אנימציות שממשיכות ללא הגבלת זמן. כל ממשקי ה-API האלה הם composables, חוץ מ-Animatable, כלומר אפשר ליצור את האנימציות האלה מחוץ לקומפוזיציה.

כל ממשקי ה-API האלה מבוססים על Animation API בסיסי יותר. למרות שרוב האפליקציות לא יפעלו ישירות עם Animation, אפשר לגשת לחלק מהיכולות להתאמה אישית שלו באמצעות ממשקי API ברמה גבוהה יותר. מידע נוסף על AnimationVector ועל AnimationSpec זמין במאמר התאמה אישית של אנימציות.

‫Animatable: אנימציה של ערך יחיד שמבוססת על קורוטינה

‫Animatable הוא placeholder לערך, שיכול להנפיש את הערך בזמן שהוא משתנה באמצעות animateTo. זהו ה-API שמשמש לגיבוי ההטמעה של animate*AsState. הוא מבטיח המשכיות עקבית ובלעדיות הדדית, מה שאומר ששינוי הערך תמיד רציף ו-Compose מבטל כל אנימציה שמתבצעת.

הרבה תכונות של Animatable, כולל animateTo, הן פונקציות השעיה. כלומר, צריך להוסיף אותן ל-CoroutineScope המתאים. לדוגמה, אפשר להשתמש ברכיב הקומפוזבילי ‏LaunchedEffect כדי ליצור היקף רק למשך משך הזמן של ערך המפתח שצוין.

// Start out gray and animate to green/red based on `ok`
val color = remember { Animatable(Color.Gray) }
LaunchedEffect(ok) {
    color.animateTo(if (ok) Color.Green else Color.Red)
}
Box(
    Modifier
        .fillMaxSize()
        .background(color.value)
)
AnimationSnippets.kt

בדוגמה הקודמת, יצרתם מופע של Animatable עם הערך ההתחלתי Color.Gray ושמרתם אותו. בהתאם לערך של הדגל הבוליאני ok, הצבע עובר אנימציה ל-Color.Green או ל-Color.Red. כל שינוי עוקב בערך הבוליאני יפעיל אנימציה לצבע השני. אם אנימציה מתבצעת בזמן שהערך משתנה, Compose מבטל את האנימציה והאנימציה החדשה מתחילה מהערך הנוכחי של התמונה עם המהירות הנוכחית.

ממשק ה-API הזה Animatable הוא ההטמעה הבסיסית של animate*AsState שמוזכרת בקטע הקודם. שימוש ישיר ב-Animatable מאפשר שליטה מדויקת יותר בכמה דרכים:

• קודם כל, הערך הראשוני של Animatable יכול להיות שונה מערך היעד הראשון שלו. לדוגמה, בדוגמת הקוד שלמעלה מוצגת תיבה אפורה בהתחלה, שמיד מונפשת לירוק או לאדום.
• שנית, Animatable מספקת יותר פעולות על ערך התוכן, במיוחד snapTo ו-animateDecay.
  • ‫snapTo מגדיר את הערך הנוכחי לערך היעד באופן מיידי. השימוש בשיטה הזו מועיל כשהאנימציה היא לא מקור האמת היחיד, והיא צריכה להסתנכרן עם מצבים אחרים, כמו אירועי מגע.
  • ‫animateDecay מתחילה אנימציה שמוצגת במהירות הולכת ופוחתת מהמהירות שצוינה. האפשרות הזו שימושית להטמעה של התנהגות של הטלה.

מידע נוסף זמין במאמר בנושא תנועות ואנימציות.

כברירת מחדל, Animatable תומך ב-Float וב-Color, אבל אפשר להשתמש בכל סוג נתונים אם מספקים TwoWayConverter. מידע נוסף זמין במאמר בנושא AnimationVector.

אפשר להתאים אישית את מפרטי האנימציה על ידי ציון AnimationSpec. מידע נוסף זמין בכתובת AnimationSpec.

‫Animation: אנימציה בשליטה ידנית

‫Animation הוא ממשק ה-API של האנימציה ברמה הכי נמוכה שזמין. הרבה מהאנימציות שראינו עד עכשיו מבוססות על Animation. יש שני תת-סוגים של Animation ‫: TargetBasedAnimation ו-DecayAnimation.

משתמשים ב-Animation רק כדי לשלוט ידנית בזמן של האנימציה. Animation הוא חסר מצב (stateless) ואין בו מושג של מחזור חיים. הוא משמש כמנוע לחישוב אנימציות עבור ממשקי API ברמה גבוהה יותר.

TargetBasedAnimation

רוב תרחישי השימוש מכוסים על ידי ממשקי API אחרים, אבל שימוש ישיר ב-TargetBasedAnimation מאפשר לכם לשלוט במשך ההפעלה של האנימציה. בדוגמה הבאה, אתם שולטים ידנית בזמן ההפעלה של TargetAnimation על סמך זמן הרינדור של הפריים שסופק על ידי withFrameNanos.

val anim = remember {
    TargetBasedAnimation(
        animationSpec = tween(200),
        typeConverter = Float.VectorConverter,
        initialValue = 200f,
        targetValue = 1000f
    )
}
var playTime by remember { mutableLongStateOf(0L) }

LaunchedEffect(anim) {
    val startTime = withFrameNanos { it }

    do {
        playTime = withFrameNanos { it } - startTime
        val animationValue = anim.getValueFromNanos(playTime)
    } while (someCustomCondition())
}
AnimationSnippets.kt

DecayAnimation

בניגוד ל-TargetBasedAnimation, ב-DecayAnimation לא צריך לספק targetValue. במקום זאת, המערכת מחשבת את targetValue על סמך תנאי ההתחלה שהוגדרו על ידי initialVelocity וinitialValue ועל סמך DecayAnimationSpec שסופק.

אנימציות של דעיכה משמשות לעיתים קרובות אחרי תנועת החלקה כדי להאט את הרכיבים עד לעצירה. מהירות האנימציה מתחילה בערך שמוגדר על ידי initialVelocityVector ומואטת לאורך זמן.