Worklet 动画系统

适用场景

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

核心概念

双线程架构与 Worklet 的意义

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

三大核心概念

基本流程

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

文档索引

根据需求快速定位（路径相对于 references/）：

强制规则

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

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

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

MUST: SharedValue 必须通过 .value 读写

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

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

MUST: 访问非 worklet 函数必须使用 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: 页面方法必须通过 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)
}

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

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

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

必须通过 runOnJS 回到 JS 线程。

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

会导致 Object.freeze 冻结 this.data，setData 将失效。

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

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

Quick Reference

API 速查表

场景 → 方案映射

相关技能

References 目录结构

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