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

בדף הזה נסביר איך ליצור אנימציות מבוססות-ערך ב-Jetpack פיתוח נייטיב, תוך התמקדות בממשקי 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 משתנה. פונקציות התוסף האלה מאפשרות להעביר את כל האנימציות של הכניסה, היציאה ו-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 האלה הם קומפוזיציות, חוץ מ-Animatable, כלומר אפשר ליצור את האנימציות האלה מחוץ לקומפוזיציה.

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

הקשר בין ממשקי API של אנימציות ברמה נמוכה — **איור 1.** הקשר בין ממשקי API של אנימציה ברמה נמוכה.

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

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

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

// 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 ומואטת לאורך זמן.

מומלץ בשבילך

הערה: טקסט הקישור מוצג כש-JavaScript מושבת
התאמה אישית של אנימציות
אנימציות ב-Compose
אנימציה של קומפוזיציות ושינויים

מגבילי אנימציה ותכנים קומפוזביליים

תמונות וקטוריות מונפשות

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

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

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

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

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

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