skyline-worklet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worklet 动画系统

Worklet Animation System

适用场景

Applicable Scenarios

实现手势跟随、拖拽等交互动画
使用 timing/spring/decay 创建动画效果
通过 SharedValue 驱动节点样式变化
组合多段动画（序列、重复、延迟）
在 UI 线程和 JS 线程间传递数据

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

双线程架构与 Worklet 的意义

Dual-Thread Architecture and the Significance of Worklet

小程序双线程架构中，UI 事件需跨线程传递到 JS 线程再回传，交互动画会有明显延迟。Worklet 动画让动画逻辑直接运行在 UI 线程，实现类原生动画体验。

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

概念	说明	关键 API
worklet 函数	可运行在 JS 或 UI 线程的函数，顶部声明 `'worklet'` 指令	`runOnUI()` , `runOnJS()`
共享变量	跨线程同步的变量，通过 `.value` 读写	`shared()` , `derived()`
动画驱动	将 SharedValue 绑定到节点样式	`applyAnimatedStyle()`

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

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 })

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

根据需求快速定位（路径相对于

references/

）：

我想要...	查阅文档
了解 worklet 架构和完整概念	`core/worklet-overview.md`
使用 SharedValue 和 DerivedValue	`base/shared-derived.md`
在 worklet 中操作 scroll-view	`base/scroll-view-context.md`
使用 timing/spring/decay 动画	`animation/timing-spring-decay.md`
查看 Easing 缓动函数	`animation/easing.md`
使用序列/重复/延迟组合动画	`animation/combine-animation.md`
了解 runOnUI/runOnJS 线程通信	`tool/thread-communication.md`

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 函数必须声明

'worklet'

指令

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
}

// ✅ 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 必须通过

.value

读写

MUST: SharedValue must be read and written via

.value

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

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

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

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

MUST: 访问非 worklet 函数必须使用

runOnJS

MUST: Access 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')
}

// ✅ 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: 页面方法必须通过

this.methodName.bind(this)

访问

MUST: Page methods must be accessed via

this.methodName.bind(this)

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

// ❌ Incorrect - 未 bind(this)，this 指向丢失
handleTap() {
  'worklet'
  runOnJS(this.showModal)(msg)
}

// ✅ 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 动画仅在 Skyline 渲染模式下可用

MUST: Worklet animations are only available in Skyline rendering mode

确保 app.json 配置
```
"renderer": "skyline"
```
- 确保开发者工具勾选「将 JS 编译成 ES5」

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

NEVER: 在 worklet 函数中直接调用

wx

API

NEVER: Directly call

wx

APIs in worklet functions

必须通过

runOnJS

回到 JS 线程。

Must return to the JS thread via

runOnJS

NEVER: 通过解构

this.data

访问属性

NEVER: Access properties by destructuring

this.data

会导致

Object.freeze

冻结

this.data

，

setData

将失效。

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

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

This will cause

Object.freeze

to freeze

this.data

, making

setData

ineffective.

// ✅ 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 速查表

API Cheat Sheet

分类	API	说明
基础	`shared(initialValue)`	创建 SharedValue
基础	`derived(updaterWorklet)`	创建衍生值（类比 computed）
基础	`cancelAnimation(sharedValue)`	取消动画
动画	`timing(toValue, options?, callback?)`	时间曲线动画（默认 300ms）
动画	`spring(toValue, options?, callback?)`	弹簧物理动画
动画	`decay(options?, callback?)`	滚动衰减动画
组合	`sequence(anim1, anim2, ...)`	依次执行
组合	`repeat(anim, reps, reverse?, callback?)`	重复（负值=无限）
组合	`delay(ms, anim)`	延迟执行
工具	`runOnUI(workletFn)`	在 UI 线程执行
工具	`runOnJS(normalFn)`	回调 JS 线程

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

场景	推荐方案
点击后平滑移动	`timing` + `Easing`
手势松开回弹	`spring`
手势松开惯性滑动	`decay` + `velocity`
先移动再弹回	`sequence(timing, spring)`
循环脉动效果	`repeat(timing, -1, true)`
延迟后开始动画	`delay(ms, timing/spring)`

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

场景	推荐技能	说明
手势组件	`skyline-components`	pan/tap/long-press 手势处理
渲染引擎概览	`skyline-overview`	Skyline 配置和迁移
样式开发	`skyline-wxss`	WXSS 支持与差异
路由转场	`skyline-route`	自定义路由动画

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 目录结构

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

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

skyline-worklet

Original

Translation

Worklet 动画系统

Worklet Animation System

适用场景

Applicable Scenarios

核心概念

Core Concepts

双线程架构与 Worklet 的意义

Dual-Thread Architecture and the Significance of Worklet

三大核心概念

Three Core Concepts

基本流程

Basic Process

文档索引

Document Index

强制规则

Mandatory Rules

MUST: worklet 函数必须声明 'worklet' 指令

MUST: worklet functions must declare the 'worklet' directive

MUST: SharedValue 必须通过 .value 读写

MUST: SharedValue must be read and written via .value

MUST: 访问非 worklet 函数必须使用 runOnJS

MUST: Access non-worklet functions must use runOnJS

MUST: 页面方法必须通过 this.methodName.bind(this) 访问

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

MUST: Worklet 动画仅在 Skyline 渲染模式下可用

MUST: Worklet animations are only available in Skyline rendering mode

NEVER: 在 worklet 函数中直接调用 wx API

NEVER: Directly call wx APIs in worklet functions

NEVER: 通过解构 this.data 访问属性

NEVER: Access properties by destructuring this.data

Quick Reference

Quick Reference

API 速查表

API Cheat Sheet

场景 → 方案映射

Scenario → Solution Mapping

相关技能

Related Skills

References 目录结构

References Directory Structure

MUST: worklet 函数必须声明
`'worklet'`
指令

MUST: worklet functions must declare the
`'worklet'`
directive

MUST: SharedValue 必须通过
`.value`
读写

MUST: SharedValue must be read and written via
`.value`

MUST: 访问非 worklet 函数必须使用
`runOnJS`

MUST: Access non-worklet functions must use
`runOnJS`

MUST: 页面方法必须通过
`this.methodName.bind(this)`
访问

MUST: Page methods must be accessed via
`this.methodName.bind(this)`

NEVER: 在 worklet 函数中直接调用
`wx`
API

NEVER: Directly call
`wx`
APIs in worklet functions

NEVER: 通过解构
`this.data`
访问属性

NEVER: Access properties by destructuring
`this.data`