Lottie
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
<!--.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
// .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
/*.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 |
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 |
repeat-count | Number | No | Indicates the number of times an animation is repeated.
Note: The default value is |
auto-reverse | Boolean | No | Specifies whether the animation is replayed automatically. Note: The default value is |
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.
|
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 |
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 Examples of low-end devices include:
Note: The default value is |
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:
//File path: mini.project.json
{
"enableAppxNg": true,
"miniprogramRoot": "dist",
"scripts": {
"beforePreview": "tnpm run build",
"beforeUpload":"tnpm run build"
},
"include":["**/*.json"] //Add this line
}