skyline-worklet

Original：🇨🇳 Chinese

Translated

Skill for Skyline Worklet Animation System. Use this skill when developing high-performance interactive animations with worklet functions, SharedValue, animation types (timing/spring/decay), Easing functions, combined animations, and thread communication (runOnUI/runOnJS). Suitable for animation scenarios that require direct UI thread response, such as dragging, gesture following, spring rebound, etc. Trigger keywords: worklet, worklet animation, SharedValue, shared variable, timing, spring, decay, Easing, runOnUI, runOnJS, applyAnimatedStyle, interactive animation, gesture animation, UI thread animation.

3installs

Sourcewechat-miniprogram/skyline-skills

Added on2026-03-25

NPX Install

npx skill4agent add wechat-miniprogram/skyline-skills skyline-worklet

SKILL.md Content (Chinese)

View Translation Comparison →

Worklet Animation System

Applicable Scenarios

Implement interactive animations such as gesture following and dragging
Create animation effects using timing/spring/decay
Drive node style changes via SharedValue
Combine multiple animations (sequence, repeat, delay)
Pass data between UI thread and JS thread

Core Concepts

Dual-Thread Architecture and the Significance of Worklet

In the mini-program dual-thread architecture, UI events need to be passed across threads to the JS thread and then returned, interactive animations will have obvious delays. Worklet animations allow animation logic to run directly on the UI thread, achieving a native-like animation experience.

Three Core Concepts

Concept	Description	Key API
worklet function	A function that can run on JS or UI thread, declared with the `'worklet'` directive at the top	`runOnUI()` , `runOnJS()`
SharedValue	A variable synchronized across threads, read and write via `.value`	`shared()` , `derived()`
Animation Driver	Bind SharedValue to node styles	`applyAnimatedStyle()`

Basic Process

js

const { shared, timing } = wx.worklet

// 1. Create SharedValue
const offset = shared(0)

// 2. Bind to node style (updater is a worklet function)
this.applyAnimatedStyle('#box', () => {
  'worklet'
  return { transform: `translateX(${offset.value}px)` }
})

// 3. Modify value to drive animation
offset.value = timing(300, { duration: 200 })

Document Index

Quickly locate based on requirements (paths are relative to

references/

):

What I want to...	Refer to Document
Understand worklet architecture and complete concepts	`core/worklet-overview.md`
Use SharedValue and DerivedValue	`base/shared-derived.md`
Operate scroll-view in worklet	`base/scroll-view-context.md`
Use timing/spring/decay animations	`animation/timing-spring-decay.md`
View Easing functions	`animation/easing.md`
Use sequence/repeat/delay combined animations	`animation/combine-animation.md`
Understand runOnUI/runOnJS thread communication	`tool/thread-communication.md`

Mandatory Rules

MUST: worklet functions must declare the

'worklet'

directive

js

// ✅ Correct
function handleGesture(evt) {
  'worklet'
  offset.value += evt.deltaX
}

// ❌ Incorrect - Missing 'worklet' directive, cannot execute on UI thread
function handleGesture(evt) {
  offset.value += evt.deltaX
}

MUST: SharedValue must be read and written via

.value

js

// ✅ Correct
const offset = shared(0)
offset.value = 100

// ❌ Incorrect - Direct assignment replaces the entire SharedValue object
const offset = shared(0)
offset = 100

MUST: Access non-worklet functions must use

runOnJS

js

// ✅ Correct
function showModal(msg) {
  wx.showModal({ title: msg })
}
function handleTap() {
  'worklet'
  const fn = this.showModal.bind(this)
  runOnJS(fn)('hello')
}

// ❌ Incorrect - Directly calling ordinary functions in worklet
function handleTap() {
  'worklet'
  this.showModal('hello')
}

MUST: Page methods must be accessed via

this.methodName.bind(this)

js

// ✅ Correct
handleTap() {
  'worklet'
  const showModal = this.showModal.bind(this)
  runOnJS(showModal)(msg)
}

// ❌ Incorrect - Missing bind(this), this pointer is lost
handleTap() {
  'worklet'
  runOnJS(this.showModal)(msg)
}

MUST: Worklet animations are only available in Skyline rendering mode

Ensure app.json is configured with
```
"renderer": "skyline"
```
Ensure "Compile JS to ES5" is checked in the developer tools

NEVER: Directly call

wx

APIs in worklet functions

Must return to the JS thread via

runOnJS

.

NEVER: Access properties by destructuring

this.data

This will cause

Object.freeze

to freeze

this.data

, making

setData

ineffective.

js

// ✅ Correct
handleTap() {
  'worklet'
  const msg = this.data.msg
}

// ❌ Incorrect - Destructuring will freeze the entire this.data
handleTap() {
  'worklet'
  const { msg } = this.data
}

Quick Reference

API Cheat Sheet

Category	API	Description
Basic	`shared(initialValue)`	Create SharedValue
Basic	`derived(updaterWorklet)`	Create derived value (analogous to computed)
Basic	`cancelAnimation(sharedValue)`	Cancel animation
Animation	`timing(toValue, options?, callback?)`	Time curve animation (300ms by default)
Animation	`spring(toValue, options?, callback?)`	Spring physics animation
Animation	`decay(options?, callback?)`	Scroll decay animation
Combine	`sequence(anim1, anim2, ...)`	Execute sequentially
Combine	`repeat(anim, reps, reverse?, callback?)`	Repeat (negative value = infinite)
Combine	`delay(ms, anim)`	Execute with delay
Tool	`runOnUI(workletFn)`	Execute on UI thread
Tool	`runOnJS(normalFn)`	Callback to JS thread

Scenario → Solution Mapping

Scenario	Recommended Solution
Smooth movement after click	`timing` + `Easing`
Rebound after gesture release	`spring`
Inertial sliding after gesture release	`decay` + `velocity`
Move first then bounce back	`sequence(timing, spring)`
Cyclic pulsation effect	`repeat(timing, -1, true)`
Start animation after delay	`delay(ms, timing/spring)`

Related Skills

Scenario	Recommended Skill	Description
Gesture components	`skyline-components`	pan/tap/long-press gesture handling
Rendering engine overview	`skyline-overview`	Skyline configuration and migration
Style development	`skyline-wxss`	WXSS support and differences
Route transition	`skyline-route`	Custom route animations

References Directory Structure

references/
├── animation/
│   ├── combine-animation.md
│   ├── easing.md
│   └── timing-spring-decay.md
├── base/
│   ├── scroll-view-context.md
│   └── shared-derived.md
├── core/
│   └── worklet-overview.md
└── tool/
    └── thread-communication.md