Animation

View Markdown

Last edited on 2026-08-11

CSS Animation

In Mini Program, CSS Transitions and CSS Animations can generally be used to create simple UI animations.

在开发者工具中预览效果

Animation Events

During an animation, you can use bind:transitionend, bind:animationstart, bind:animationiteration, and bind:animationend to listen for animation events.

Event Name Description
transitionend CSS transition ends (or the animation created using the keyframes API ends)
animationstart CSS animation starts
animationiteration CSS animation completes one iteration
animationend CSS animation ends

Note: These events are not bubbling events. They must be bound to the node where the animation actually occurs to take effect.

Keyframe Animation

基础库 2.9.0 开始支持,低版本需做兼容处理。

Supported only by the WebView rendering engine.

Mini Program The Base Library provides a more user-friendly method for creating animations, serving as an alternative to the legacy wx.createAnimation. It offers better performance and a more controllable interface.

In pages or custom components, when you need to perform keyframe animations, you can use the this.animate interface:

this.animate(selector, keyframes, duration, callback)

Parameters

Attribute Type Default Required Description
selector String Yes Selector (same format as the selector in SelectorQuery.select)
keyframes Array Yes Keyframe information
duration Number Yes Animation duration (in milliseconds)
callback function No Callback function triggered after the animation completes

Structure of objects in keyframes

Attribute Type Default Required Description
offset Number No Offset of the keyframe, range [0-1]
ease String linear No Animation easing function
transformOrigin String No Origin position, i.e., CSS transform-origin
backgroundColor String No Background color, i.e., CSS background-color
opacity Number No Opacity, i.e., CSS opacity
width String No Width, i.e., CSS width
height String No Height, i.e., CSS height
left String No Left position, i.e., CSS left
top String No Top position, i.e., CSS top
right String No Right position, i.e., CSS right
bottom String No Bottom position, i.e., CSS bottom
matrix Array No Transformation matrix, i.e., CSS transform matrix
matrix3d Array No 3D transformation matrix, i.e., CSS transform matrix3d
rotate Number No Rotation, i.e., CSS transform rotate
rotate3d Array No 3D rotation, i.e., CSS transform rotate3d
rotateX Number No Rotation on X-axis, i.e., CSS transform rotateX
rotateY Number No Rotation on Y-axis, i.e., CSS transform rotateY
rotateZ Number No Rotation on Z-axis, i.e., CSS transform rotateZ
scale Array No Scaling, i.e., CSS transform scale
scale3d Array No 3D scaling, i.e., CSS transform scale3d
scaleX Number No Scaling on X-axis, i.e., CSS transform scaleX
scaleY Number No Scaling on Y-axis, i.e., CSS transform scaleY
scaleZ Number No Scaling on Z-axis, i.e., CSS transform scaleZ
skew Array No Skewing, i.e., CSS transform skew
skewX Number No Skewing on X-axis, i.e., CSS transform skewX
skewY Number No Skewing on Y-axis, i.e., CSS transform skewY
translate Array No Translation, i.e., CSS transform translate
translate3d Array No 3D translation, i.e., CSS transform translate3d
translateX Number No Translation on X-axis, i.e., CSS transform translateX
translateY Number No Translation on Y-axis, i.e., CSS transform translateY
translateZ Number No Translation on Z-axis, i.e., CSS transform translateZ

Sample Code

在开发者工具中预览效果


  this.animate('#container', [
    { opacity: 1.0, rotate: 0, backgroundColor: '#FF0000' },
    { opacity: 0.5, rotate: 45, backgroundColor: '#00FF00'},
    { opacity: 0.0, rotate: 90, backgroundColor: '#FF0000' },
    ], 5000, function () {
      this.clearAnimation('#container', { opacity: true, rotate: true }, function () {
        console.log("Cleared opacity and rotate properties on #container")
      })
  }.bind(this))

  this.animate('.block', [
    { scale: [1, 1], rotate: 0, ease: 'ease-out'  },
    { scale: [1.5, 1.5], rotate: 45, ease: 'ease-in', offset: 0.9},
    { scale: [2, 2], rotate: 90 },
  ], 5000, function () {
    this.clearAnimation('.block', function () {
      console.log("Cleared all animation properties on .block")
    })
  }.bind(this))

After calling the animate API, additional style properties are added to the node, overriding the original corresponding styles. If you need to remove these styles, use this.clearAnimation on the node after all its animations have completed.

this.clearAnimation(selector, options, callback)

Parameters

Property Type Default Required Description
selector String Yes Selector (same format as the selector in SelectorQuery.select)
options Object No Properties to clear. If not specified, all properties are cleared.
callback Function No Callback function to be executed after clearing is complete.

Scroll-Driven Animations

基础库 2.9.0 开始支持,低版本需做兼容处理。

Supported only by the WebView rendering engine.

Progressively changing animation progress based on scroll position is a common scenario. This type of animation creates a seamless and natural interaction experience, enhancing user engagement. Therefore, the Mini Program base library also supports a scroll-driven animation mechanism.

Building upon the aforementioned keyframe animation interface, a new ScrollTimeline parameter has been introduced to bind a scrollable element (currently only scroll-view is supported). The interface definition is as follows:

this.animate(selector, keyframes, duration, ScrollTimeline)

Object Structure of ScrollTimeline

Attribute Type Default Required Description
scrollSource String Yes The selector for the scrollable element (only scroll-view is supported). Scrolling this element drives the animation progress.
orientation String vertical No Specifies the scroll direction. Valid values are horizontal or vertical.
startScrollOffset Number Yes The scroll offset (in px) at which the animation progress starts being driven.
endScrollOffset Number Yes The scroll offset (in px) at which the animation progress stops being driven.
timeRange Number Yes The time duration (in ms) mapped to the start and end scroll range. This duration can be used to match the time (duration) in keyframe animations.

Sample Code

在开发者工具中预览效果

  this.animate('.avatar', [{
    borderRadius: '0',
    borderColor: 'red',
    transform: 'scale(1) translateY(-20px)',
    offset: 0,
  }, {
    borderRadius: '25%',
    borderColor: 'blue',
    transform: 'scale(.65) translateY(-20px)',
    offset: .5,
  }, {
    borderRadius: '50%',
    borderColor: 'blue',
    transform: `scale(.3) translateY(-20px)`,
    offset: 1
  }], 2000, {
    scrollSource: '#scroller',
    timeRange: 2000,
    startScrollOffset: 0,
    endScrollOffset: 85,
  })

  this.animate('.search_input', [{
    opacity: '0',
    width: '0%',
  }, {
    opacity: '1',
    width: '100%',
  }], 1000, {
    scrollSource: '#scroller',
    timeRange: 1000,
    startScrollOffset: 120,
    endScrollOffset: 252
  })

Advanced Animation Techniques

In complex scenarios, the animation methods described above may not be applicable.

If you are using the Skyline rendering engine, you can utilize worklet animations.

The WXS responsive events approach allows you to dynamically adjust the style attributes of nodes by using WXS to respond to events. By continuously modifying the style attribute values, you can achieve animation effects. Additionally, this method can dynamically generate animations based on user touch events.

Sequentially using setData to update the interface can also produce animation effects. While this approach allows for arbitrary interface changes, it typically results in significant latency or lag, and may even cause the Mini Program to freeze. In such cases, performance can be improved by switching the page-level setData to setData within custom components. The following example demonstrates how to implement a stopwatch animation using setData.

在开发者工具中预览效果