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.