skyline-worklet

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 through SharedValue
• Combine multiple animation segments (sequence, repeat, delay)
• Pass data between the UI thread and the JS thread

Core concepts

Dual-thread architecture and the significance of Worklet

In the Mini Program dual-thread architecture, UI events must be passed across threads to the JS thread and then sent back,interactive animations will have noticeable delay. Worklet animations run animation logic directly on the UI thread, delivering a near-native animation experience.

Three core concepts

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

Basic flow

const { shared, timing } = wx.worklet

// 1. 创建共享变量
const offset = shared(0)

// 2. 绑定到节点样式（updater 为 worklet 函数）
this.applyAnimatedStyle('#box', () => {
  'worklet'
  return { transform: `translateX(${offset.value}px)` }
})

// 3. 修改值驱动动画
offset.value = timing(300, { duration: 200 })

Documentation index

Quickly locate based on needs (paths are relative to references/）：

I want to...	Consult the documentation
Understand the worklet architecture and complete concepts	core/worklet-overview.md
Use SharedValue and DerivedValue	base/shared-derived.md
Operate scroll-view in a 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 composite animations	animation/combine-animation.md
Understand runOnUI/runOnJS thread communication	tool/thread-communication.md

Mandatory rules

MUST: worklet functions must declare the 'worklet' directive

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

// ❌ Incorrect - 缺少 'worklet' 指令，无法在 UI 线程执行
function handleGesture(evt) {
  offset.value += evt.deltaX
}

MUST: SharedValue must be read and written through .value read/write

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

// ❌ Incorrect - 直接赋值会替换整个 SharedValue 对象
const offset = shared(0)
offset = 100

MUST: Accessing non-worklet functions must use runOnJS

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

// ❌ Incorrect - worklet 中直接调用普通函数
function handleTap() {
  'worklet'
  this.showModal('hello')
}

MUST: Page methods must be accessed through this.methodName.bind(this) access

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

// ❌ Incorrect - 未 bind(this)，this 指向丢失
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 the developer tools option "Compile JS to ES5" is checked

NEVER: Directly call in a worklet function wx API

Must use runOnJS to return to the JS thread.

NEVER: Access properties by destructuring this.data access property

This will cause Object.freeze to freeze this.data，setData and become invalid.

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

// ❌ Incorrect - 解构会冻结整个 this.data
handleTap() {
  'worklet'
  const { msg } = this.data
}

Quick Reference

API quick reference

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

Scenario → solution mapping

Scenario	Recommended solution
Smooth movement after tap	timing + Easing
Rebound on gesture release	spring
Inertial sliding on gesture release	decay + velocity
Move first, then rebound	sequence(timing, spring)
Looping pulse effect	repeat(timing, -1, true)
Start animation after delay	delay(ms, timing/spring)

Related skills

Scenario	Recommended skill	Description
Gesture component	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 transitions	skyline-route	Custom route animation

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