React Native Academy · 课时

Worklet 与在 UI 线程上运行代码

使用“worklet”指令将函数标记为 worklet，了解其绕过 JS 桥接的原因，并编写可直接更新共享值的手势处理函数。

Worklet 与在 UI 线程上运行代码 是 CoddyKit 上的免费 React Native Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 React Native Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Native Academy 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

What Is a Worklet?

A worklet is a JavaScript function that Reanimated runs on the UI thread instead of the JavaScript thread. Reanimated's Babel plugin detects functions marked with the 'worklet' directive string at the top of their body and transforms them at build time into a form that can be sent to and executed on the UI thread.

Worklets are the core mechanism that allows Reanimated to process gesture data and update animations frame-by-frame at 60fps without ever involving the JavaScript thread or the bridge. They are the key architectural innovation that separates Reanimated from the classic Animated API.

function clamp(value, min, max) {
  'worklet'; // directive marks this as a worklet
  return Math.min(Math.max(value, min), max);
}

// This function can now be called inside
// useAnimatedStyle, useAnimatedGestureHandler,
// and other Reanimated hooks

The 'worklet' Directive

The 'worklet' string literal at the top of a function body is a special directive — similar to 'use strict'. The Reanimated Babel plugin scans for it and transforms the function so it can be serialized and run on the UI thread. Without this directive, calling the function from a worklet context would silently execute on the JS thread, causing potential crashes or incorrect behavior.

Functions passed to Reanimated hooks like useAnimatedStyle are automatically treated as worklets even without the directive. Regular utility functions called FROM those hooks need the directive explicitly.

// Automatically a worklet — Reanimated knows:
const animatedStyle = useAnimatedStyle(() => {
  return { opacity: opacity.value };
});

// Utility function needs explicit directive:
function mapRange(value, inMin, inMax, outMin, outMax) {
  'worklet';
  return ((value - inMin) / (inMax - inMin)) * (outMax - outMin) + outMin;
}

Why the UI Thread Matters for Gestures

Touch events on mobile are processed on the UI thread. When a user drags a finger, the device generates touch events many times per second (up to 120fps on modern devices). If gesture handling required the JavaScript thread, every touch event would cross the bridge — introducing latency that makes interactions feel laggy and unresponsive.

With worklets, the gesture handler and the animation response both run on the UI thread. The animated value updates happen in the same thread tick as the touch event, achieving true zero-latency gesture response that feels like native iOS/Android interactions.

Calling Worklets from Animated Handlers

Reanimated provides hooks like useAnimatedScrollHandler and useAnimatedGestureHandler whose callbacks run as worklets on the UI thread. Inside these callbacks you can call any function marked with 'worklet' directly, and you can read and write shared values using .value.

Writing to a shared value inside a gesture callback is how you make an animated component track the user's finger in real time — the write happens on the UI thread and the animated style reacts immediately.

import { useAnimatedScrollHandler, useSharedValue } from 'react-native-reanimated';

const scrollY = useSharedValue(0);

const scrollHandler = useAnimatedScrollHandler({
  onScroll: (event) => {
    'worklet';
    scrollY.value = event.contentOffset.y;
  },
});

runOnJS: Calling React from Worklets

Worklets run on the UI thread and cannot directly call React functions, setState, or navigation methods. When you need to trigger JavaScript-thread code from a worklet (for example, updating React state or navigating after a gesture completes), use runOnJS.

runOnJS(fn)(args) schedules the function to run on the JS thread on the next available frame. This lets gesture handlers update React state or call navigation after an interaction without breaking the worklet execution model.

import { runOnJS } from 'react-native-reanimated';

const [dismissed, setDismissed] = React.useState(false);

// Inside a gesture handler worklet:
function onSwipeComplete() {
  'worklet';
  // Cannot call setDismissed directly from UI thread!
  runOnJS(setDismissed)(true); // schedules on JS thread
}

runOnUI: Calling Worklets from JS Thread

The reverse of runOnJS is runOnUI. This lets you schedule a worklet function to execute on the UI thread from the JavaScript thread. It is useful for triggering animations from JS-thread event handlers (like button presses) while keeping the animation logic itself in a worklet.

In most cases you simply assign to sharedValue.value (which already runs on the UI thread), so runOnUI is less commonly needed. It becomes necessary when you need to batch multiple UI-thread operations atomically.

import { runOnUI } from 'react-native-reanimated';

function triggerComplexAnimation() {
  runOnUI(() => {
    'worklet';
    // These run atomically on the UI thread:
    offset.value = withSpring(200);
    scale.value = withTiming(0.8, { duration: 300 });
    opacity.value = withTiming(0.5, { duration: 300 });
  })();
}

Limitations of Worklets

Worklets are not full JavaScript — they run in a restricted environment that cannot access Node.js APIs, React hooks, component state, or the full JavaScript runtime. You cannot console.log from a worklet in production (it is a no-op). You cannot import third-party modules inside a worklet unless they explicitly support Reanimated.

Keep worklets focused on math and value computation: clamping, mapping ranges, computing physics, reading gesture data. Move everything else to the JS thread using runOnJS.

function gestureHandler(event) {
  'worklet';
  // OK in worklets:
  const clamped = Math.max(0, Math.min(event.translationX, 300));
  offset.value = clamped;

  // NOT OK in worklets:
  // console.log('position:', clamped); // no-op in prod
  // setReactState(clamped); // crashes - use runOnJS
  // navigation.navigate('Screen'); // crashes - use runOnJS
}

useAnimatedReaction for Watching Values

useAnimatedReaction lets you watch a shared value or derived expression and run a worklet (or call back to JS) when it changes. It takes two worklet functions: a prepare function that reads values, and a reaction function that receives the current and previous values.

This is useful for triggering side effects when an animation reaches a threshold — like calling navigation to dismiss a screen when an offset exceeds 50% of the screen height.

import { useAnimatedReaction, runOnJS } from 'react-native-reanimated';

useAnimatedReaction(
  () => offset.value,           // prepare: what to watch
  (currentValue, previousValue) => { // reaction: what to do
    'worklet';
    if (currentValue > 200 && previousValue <= 200) {
      runOnJS(onDismiss)(); // notify JS thread
    }
  }
);

useDerivedValue for Computed Shared Values

useDerivedValue creates a new shared value that is automatically computed from other shared values. The derivation function is a worklet that runs on the UI thread whenever any dependency changes. It is the Reanimated equivalent of useMemo, but for shared values.

Use derived values to compute complex transformations once (rather than repeating the math in each useAnimatedStyle) or to drive multiple style hooks from a single source of truth.

import { useDerivedValue } from 'react-native-reanimated';

const progress = useSharedValue(0); // 0 to 1

// Derived: convert progress to translateX
const translateX = useDerivedValue(() => {
  'worklet';
  return progress.value * 300;
});

// Derived: convert progress to opacity (inverse)
const opacity = useDerivedValue(() => {
  'worklet';
  return 1 - progress.value;
});

Worklets in Practice: Scroll Parallax

A scroll parallax header demonstrates worklets in practice. The scroll offset drives multiple derived values — a background image moves at half speed, a title fades out, and a sticky mini-header fades in. All these derivations run as worklets triggered by Animated.event scroll tracking.

The entire parallax effect runs at 60fps with zero JavaScript thread involvement because every step — scroll tracking, value derivation, and style computation — is a worklet on the UI thread.

const scrollY = useSharedValue(0);

const bgTranslateY = useDerivedValue(() => scrollY.value * 0.5);
const titleOpacity = useDerivedValue(() =>
  Math.max(0, 1 - scrollY.value / 100)
);

const bgStyle = useAnimatedStyle(() => ({
  transform: [{ translateY: bgTranslateY.value }],
}));
const titleStyle = useAnimatedStyle(() => ({
  opacity: titleOpacity.value,
}));

Debugging Worklets

Debugging worklets is harder than regular JavaScript because they run on a separate thread. Use console.log inside worklets during development (it works in debug mode via Hermes), and use useAnimatedReaction with runOnJS(console.log) for production-safe logging.

Reanimated also integrates with React DevTools Profiler to visualize which worklets are running. If animations behave unexpectedly, add a useDerivedValue to log the computed value at each frame to identify where the calculation diverges from expectations.

// Development: console.log works in Hermes debug
useAnimatedStyle(() => {
  console.log('offset:', offset.value); // OK in dev mode
  return { transform: [{ translateX: offset.value }] };
});

// Production-safe logging via runOnJS:
useAnimatedReaction(
  () => offset.value,
  (val) => runOnJS(console.log)('offset:', val)
);

Quick Check

Test your understanding of React Native Mobile Development concepts from this lesson.

Lesson Recap

In this lesson you learned: worklets are functions marked with the 'worklet' directive that run on the UI thread bypassing the bridge, runOnJS schedules JS-thread calls from worklets for React state and navigation, and useDerivedValue and useAnimatedReaction let you derive and watch shared values in worklet context. Next up we build a draggable card using Pan gestures with React Native Gesture Handler.

常见问题解答

「Worklet 与在 UI 线程上运行代码」课时是免费的吗？

是的 — 「Worklet 与在 UI 线程上运行代码」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Native Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Native Academy 课程共包含 4 节课。

「Worklet 与在 UI 线程上运行代码」这节课中我会学到什么？

使用“worklet”指令将函数标记为 worklet，了解其绕过 JS 桥接的原因，并编写可直接更新共享值的手势处理函数。你通过在浏览器中直接运行的动手代码来练习 React Native Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 React Native Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 React Native Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「Worklet 与在 UI 线程上运行代码」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 React Native Academy 课中编写并运行代码吗？

能。每节 React Native Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 React Native Academy