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

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
}