Lottie

2022-07-29 10:25

This topic introduces what Lottie is and how to use Lottie animation.

Overview

Lottie is a library for Web, iOS, and Android that renders Adobe After Effects animations in JSON data format using Bodymovin on mobile devices. This document provides the method to adapt the Lottie animation library to mini programs. For more information about Lottie, see Lottie official document and Lottie Supported Features. To learn the supported API, see my.createLottieContext.

Usage

Sample code

.axml

copy
<!--.axml-->
<lottie
        assets-path="{{item.assetsPath}}" 
        autoplay="{{item.autoplay}}" 
        id="{{item.id}}"
        django-id="{{item.djangoId}}"
        path="{{item.path}}" 
        repeat-count="{{item.repeatCount}}"
        placeholder="{{item.placeholder}}"
        class="item">
  </lottie>

.js

copy
// .js 
Page({
  data: {
    id : 'lottie-1',
    desc : 'Django auto play and low-end device optimized',
    autoplay : true,
    djangoId：'https://gw.alipayobjects.com/os/basement_prod/1af0a9dc-110a-4a59-9084-a03d45686c8c.zip'
    placeholder:'https://gw.alipayobjects.com/mdn/rms_e345fe/afts/img/A*nu3GTaHqJ9AAAAAAAAAAAAAAARQnAQ524560995883_icon_S.png',
    optimize : 'true',
    repeatCount : -1    
  },
  onReady() {
    var lottieContext = my.createLottieContext(elementId);
    lottieContext.play()
  }
})

.acss

copy
/*.acss*/
.item{
  width: 700rpx;
  height: 400rpx;
  /* opacity: 0.5; */
}

Parameters

Parameter	Data type	Required	Description
autoplay	Boolean	No	Specifies whether the animation plays automatically. Note: The default value is `false`, which means the animation does not play automatically.
path	String	No	Indicates the path of Lottie resources in the mini program, which includes the JSON file path of the near end (in-package) and the far end (web). Note: If both path and django-id are passed, only one of them is specified.
speed	Float	No	Indicates the speed of the animation. A positive number indicates the animation's fast forward speed while a negative number indicates the animation's rewound speed. Note: The default value is `1.0`, which means the animation is played at normal speed.
repeat-count	Number	No	Indicates the number of times an animation is repeated. Negative number: The animation is repeated countless times. 0: The animation is not repeated and is only played once. 1: The animation is repeated once and is played twice. Note: The default value is `0`, which means the animation is not repeated.
auto-reverse	Boolean	No	Specifies whether the animation is replayed automatically. Note: The default value is `false`, which means the animation is not automatically replayed.
assets-path	String	No	Indicates the resource path. "/" means the path is the root directory of the mini program.
placeholder	String	Yes	Indicates the default image or optimized image path that is applied when Lottie is loading or loads incorrectly. Local resources are supported, for example, '/image/lottie/lottie2_default.png' HTTP CDN path and near-end path are supported.
django-id	String	No	Indicates the online Lottie resource path (the far-end ZIP file path). Lottie components will perform MD5 validation, decompression, acquisition, and other processing, and display default images (specified by the placeholder parameter) during the process. Note: If both path and django-id are passed, only one of them is specified.
md5	String	No	Indicates the MD5 validation for online resources. For example, if the value of django-Id is `https://b.zip`, you can use `b.zip` for encryption to get the MD5 value `"77c6c86fc89ba94cc0a9271b77ae77d2"`.
optimize	Boolean	No	In the case of low-end devices, Lottie animation will be optimized and displayed as the default image specified by the placeholder parameter. When the value of optimize is `true` and the placeholder image is passed in, low-end devices will only display the image other than Lottie. Examples of low-end devices include: iOS: Less than or equal to iPhone 6 Plus. Android: Memory capacity less than 3GB. Note: The default value is `false`, which means Lottie is displayed.
onDataReady	EventHandle	-	Triggered when the data downloading and view creation are complete.
onDataFailed	EventHandle	-	Triggered when the data loading failed.
onAnimationStart	EventHandle	-	Triggered when the animation starts.
onAnimationEnd	EventHandle	-	Triggered when the animation ends.
onAnimationRepeat	EventHandle	-	Triggered at the end of a replay of the animation.
onAnimationCancel	EventHandle	-	Triggered when the animation is canceled.
onDataLoadReady	EventHandle	-	Triggered when the data loading is ready during parameterization and waiting for the parameterized value to be passed in.

Functions

When the mini program integrates Lottie, the following functions are supported:

Resource file handling: Deal with images and resources in Lottie.
Custom play: Achieve the custom play capability without an external button designed to control play.

Resource file handling

Image files

The Lottie animation provided by UI designers may contain the "images/" directory, which includes some static images. For this scenario, there are two ways to pass image files:

Compress the entire file into a ZIP file, then pass the path of the ZIP file to the django-id parameter.
Convert an image to a base64 URL and write it in the JSON file, so that the path of the JSON file is passed to the path parameter.

More information

Virtual device testing

To improve accuracy, try to test with various mobile device models of different operating systems.

Turn animations off in the Developer options

If Lottie animations have been loaded, you can choose to turn animations off in the Developer options. Once animations are turned off, you need to restart the app or reload to enable Lottie again.

Create animation again when running in the foreground

For iOS, the system will automatically remove animations once the app is running in the background, so the animations need to be created again once the app is running in the foreground.

Unique Lottie component IDs within the app

It's recommended that the Lottie component IDs of the mini program be unique within the app. For the same Lottie component on different pages, the component may not be destroyed when switching pages. Therefore, we recommend you not to reuse the same component ID on different pages, for example, reuse the same Like button ID on different video pages.

File compressing

Compress the file directly in the current directory, not in the outer directory. Currently, traversing directories to find JSON files is not supported. If no JSON files are found in the first layer after decompression, it will be considered illegal.

The solution to support local JSON files is as follows:

copy
//File path: mini.project.json
{
  "enableAppxNg": true,
  "miniprogramRoot": "dist",
  "scripts": {
  "beforePreview": "tnpm run build",
  "beforeUpload":"tnpm run build"
},
"include":["**/*.json"] //Add this line
}