Animations des cartes

Les cartes sont compatibles avec plusieurs approches d'animation, y compris les suivantes :

Afficher une transition "Balayage"

Pour afficher un balayage fluide d'une valeur à une autre, vous pouvez activer les animations d'interpolation pour un élément, comme illustré dans l'extrait de code suivant :

private var startValue = 15f
private var endValue = 105f
private val animationDurationInMillis = 2000L // 2 seconds

override fun onTileRequest(requestParams: RequestBuilders.TileRequest): ListenableFuture<Tile> {
    val circularProgressIndicator =
        CircularProgressIndicator.Builder()
            .setProgress(
                FloatProp.Builder(/* static value */ 0.25f)
                    .setDynamicValue(
                        // Or you can use some other dynamic object, for example
                        // from the platform and then at the end of expression
                        // add animate().
                        DynamicFloat.animate(
                            startValue,
                            endValue,
                            AnimationSpec.Builder()
                                .setAnimationParameters(
                                    AnimationParameters.Builder()
                                        .setDurationMillis(animationDurationInMillis)
                                        .build()
                                )
                                .build(),
                        )
                    )
                    .build()
            )
            .build()

    return Futures.immediateFuture(
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setTileTimeline(Timeline.fromLayoutElement(circularProgressIndicator))
            .build()
    )
}
Animations.kt

Définir la direction de l'arc

Si votre tuile contient un arc, vous ne souhaitez peut-être pas que la ligne ou le texte de l'arc se développent toujours dans le sens de lecture par défaut de la langue choisie par l'utilisateur. Pour spécifier une direction de croissance d'arc, utilisez les API ArcDirection :

public override fun onTileRequest(
    requestParams: RequestBuilders.TileRequest
): ListenableFuture<Tile> {
    return Futures.immediateFuture(
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setTileTimeline(
                Timeline.fromLayoutElement(
                    EdgeContentLayout.Builder(deviceParameters)
                        .setResponsiveContentInsetEnabled(true)
                        .setEdgeContent(
                            Arc.Builder()
                                // Arc should always grow clockwise.
                                .setArcDirection(LayoutElementBuilders.ARC_DIRECTION_CLOCKWISE)
                                .addContent(
                                    ArcLine.Builder()
                                        // Set color, length, thickness, and more.
                                        // Arc should always grow clockwise.
                                        .setArcDirection(
                                            LayoutElementBuilders.ARC_DIRECTION_CLOCKWISE
                                        )
                                        .build()
                                )
                                .build()
                        )
                        .build()
                )
            )
            .build()
    )
}
Animations.kt

Afficher un fondu ou un glissement fluide

Pour indiquer plus clairement qu'un élément apparaît ou disparaît dans une carte, ou pour afficher plus subtilement un changement dans la valeur d'une carte, utilisez des effets de fondu et de glissement dans vos animations de carte.

Si une mise en page de carte contient un élément dont la valeur change, la carte affiche l'animation de sortie de l'élément, puis met à jour la mise en page et affiche l'animation d'entrée de l'élément.

Transitions "Fondu"

L'extrait de code suivant montre comment effectuer des transitions de fondu en entrée et en sortie à l'aide des méthodes d'assistance de DefaultContentTransitions. Pour définir des objets FadeInTransition et FadeOutTransition personnalisés, appelez respectivement setFadeIn() et setFadeOut() dans les méthodes setter de la transition.

public override fun onTileRequest(
    requestParams: RequestBuilders.TileRequest
): ListenableFuture<Tile> {
    // Assumes that you've defined a custom helper method called
    // getTileTextToShow().
    val tileText = getTileTextToShow()
    return Futures.immediateFuture(
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setTileTimeline(
                Timeline.fromLayoutElement(
                    Text.Builder(this, tileText)
                        .setModifiers(
                            Modifiers.Builder()
                                .setContentUpdateAnimation(
                                    AnimatedVisibility.Builder()
                                        .setEnterTransition(DefaultContentTransitions.fadeIn())
                                        .setExitTransition(DefaultContentTransitions.fadeOut())
                                        .build()
                                )
                                .build()
                        )
                        .build()
                )
            )
            .build()
    )
}
Animations.kt

Transitions "Glissement"

Cet autre extrait de code montre comment effectuer des transitions de glissement en entrée et en sortie à l'aide des méthodes d'assistance de DefaultContentTransitions. Vous pouvez également définir des objets SlideInTransition et SlideOutTransition personnalisés en appelant respectivement setSlideIn() et setSlideOut() dans les méthodes setter de la transition.

public override fun onTileRequest(
    requestParams: RequestBuilders.TileRequest
): ListenableFuture<Tile> {
    // Assumes that you've defined a custom helper method called
    // getTileTextToShow().
    val tileText = getTileTextToShow()
    return Futures.immediateFuture(
        Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setTileTimeline(
                Timeline.fromLayoutElement(
                    Text.Builder(this, tileText)
                        .setModifiers(
                            Modifiers.Builder()
                                .setContentUpdateAnimation(
                                    AnimatedVisibility.Builder()
                                        .setEnterTransition(
                                            DefaultContentTransitions.slideIn(
                                                ModifiersBuilders.SLIDE_DIRECTION_LEFT_TO_RIGHT
                                            )
                                        )
                                        .setExitTransition(
                                            DefaultContentTransitions.slideOut(
                                                ModifiersBuilders.SLIDE_DIRECTION_LEFT_TO_RIGHT
                                            )
                                        )
                                        .build()
                                )
                                .build()
                        )
                        .build()
                )
            )
            .build()
    )
}
Animations.kt

Afficher une transformation

Pour attirer l'attention sur un élément ou une zone spécifiques d'une tuile, vous pouvez lui appliquer plusieurs types de transformations, y compris la rotation, la mise à l'échelle et la translation.

De nombreuses valeurs à virgule flottante associées aux transformations acceptent les expressions dynamiques, qui vous permettent d'animer ces transformations.

Rotation

Pour effectuer une rotation dans le sens des aiguilles d'une montre autour d'un point de pivot personnalisable, utilisez un code semblable à celui-ci :

return Futures.immediateFuture(
    Tile.Builder()
        .setResourcesVersion(RESOURCES_VERSION)
        .setTileTimeline(
            Timeline.fromLayoutElement(
                Text.Builder(this, someTileText)
                    .setModifiers(
                        Modifiers.Builder()
                            .setTransformation(
                                ModifiersBuilders.Transformation.Builder()
                                    // Set the pivot point 50 dp from the left edge
                                    // and 100 dp from the top edge of the screen.
                                    .setPivotX(dp(50f))
                                    .setPivotY(dp(100f))
                                    // Rotate the element 45 degrees clockwise.
                                    .setRotation(degrees(45f))
                                    .build()
                            )
                            .build()
                    )
                    .build()
            )
        )
        .build()
)
Animations.kt

Mettre à l'échelle

Pour agrandir ou réduire un élément à l'aide de facteurs de scaling horizontal et vertical, utilisez un code semblable à ce qui suit :

return Futures.immediateFuture(
    Tile.Builder()
        .setResourcesVersion(RESOURCES_VERSION)
        .setTileTimeline(
            Timeline.fromLayoutElement(
                Text.Builder(this, someTileText)
                    .setModifiers(
                        Modifiers.Builder()
                            .setTransformation(
                                ModifiersBuilders.Transformation.Builder()
                                    // Set the pivot point 50 dp from the left edge
                                    // and 100 dp from the top edge of the screen.
                                    .setPivotX(dp(50f))
                                    .setPivotY(dp(100f))
                                    // Shrink the element by a scale factor
                                    // of 0.5 horizontally and 0.75 vertically.
                                    .setScaleX(FloatProp.Builder(0.5f).build())
                                    .setScaleY(FloatProp.Builder(0.75f).build())
                                    .build()
                            )
                            .build()
                    )
                    .build()
            )
        )
        .build()
)
Animations.kt

Traduction géométrique

Pour déplacer un élément d'un nombre spécifique de pixels de densité (dp) sur l'écran horizontalement ou verticalement, utilisez un code semblable à ce qui suit :

return Futures.immediateFuture(
    Tile.Builder()
        .setResourcesVersion(RESOURCES_VERSION)
        .setTileTimeline(
            Timeline.fromLayoutElement(
                Text.Builder(this, someTileText)
                    .setModifiers(
                        Modifiers.Builder()
                            .setTransformation(
                                ModifiersBuilders.Transformation.Builder()
                                    // Translate (move) the element 60 dp to the right
                                    // and 80 dp down.
                                    .setTranslationX(dp(60f))
                                    .setTranslationY(dp(80f))
                                    .build()
                            )
                            .build()
                    )
                    .build()
            )
        )
        .build()
)
Animations.kt

Animations Lottie

Les cartes sont compatibles avec la lecture des animations Lottie, à l'aide d'une syntaxe semblable à celle des images :

class LottieAnimation : TileService() {

    val lottieResourceId = "lottie_animation"

    override fun onTileRequest(requestParams: RequestBuilders.TileRequest): ListenableFuture<Tile> {

        val layout =
            LayoutElementBuilders.Image.Builder()
                .setWidth(dp(150f))
                .setHeight(dp(150f))
                .setResourceId(lottieResourceId)
                .build()

        return Futures.immediateFuture(
            Tile.Builder()
                .setResourcesVersion(RESOURCES_VERSION)
                .setTileTimeline(Timeline.fromLayoutElement(layout))
                .build()
        )
    }

    override fun onTileResourcesRequest(
        requestParams: ResourcesRequest
    ): ListenableFuture<Resources> {

        val lottieImage =
            ResourceBuilders.ImageResource.Builder()
                .setAndroidLottieResourceByResId(
                    ResourceBuilders.AndroidLottieResourceByResId.Builder(R.raw.lottie)
                        .setStartTrigger(createOnVisibleTrigger())
                        .build()
                )
                .build()

        return Futures.immediateFuture(
            Resources.Builder()
                .setVersion(requestParams.version)
                .addIdToImageMapping(lottieResourceId, lottieImage)
                .build()
        )
    }
}

Animations.kt

Quelques points à noter :

  • Seul un sous-ensemble de fichiers Lottie est accepté. Vérifiez la compatibilité à l'aide de l'un des validateurs suivants :
    • Un outil de validation en ligne : https://skottie.skia.org/. Dans la section "Rapport de compatibilité", le fichier doit réussir les tests "Erreurs de spécification", "Avertissements de spécification" (avec les propriétés communes ignorées) et "Erreurs de profil basse consommation".
    • Bibliothèque de validation Rust : https://github.com/google/lottie-tools.
  • La lecture Lottie est compatible avec les moteurs de rendu de tuiles dont la version majeure est au moins 1 et la version mineure au moins 500. Si une animation donnée n'est pas prise en charge, elle n'apparaît pas, mais le reste du bloc s'affiche comme prévu. Si nécessaire, vous pouvez fournir une option de secours, comme une image statique.

Ne pas afficher d'informations importantes au milieu d'une animation

Les animations sont parfois désactivées :

  • Le rendu des cartes du système peut désactiver les animations pour toutes les cartes.
  • Une carte ne peut animer que quatre éléments à la fois. Si vous essayez d'animer plus de quatre éléments en même temps, tous n'affichent pas une animation.

Dans le cas où une animation est désactivée, les éléments sont statiques et affichent la valeur de fin de l'animation. Pour cette raison, ne comptez pas sur le comportement de l'animation, comme sa durée, pour afficher des informations importantes.