react-native-worklets
@amazon-devices/react-native-worklets是React Native多线程库,为Reanimated的性能功能提供基础支持。您可以在多个线程和运行时上并行执行JavaScript代码,从而实现流畅的动画和交互,避免阻塞主线程。
什么是Worklet?
Worklet是可序列化并在不同线程上执行的JavaScript函数。当您使用'worklet'指令标记函数时,Babel插件会将其转换为可序列化的格式,以便复制并在用户界面线程或其他自定义运行时上执行。
主要功能
- 多线程: 在不同的线程(用户界面线程、自定义worklet运行时)上执行JavaScript代码
- 零副本序列化: 在线程间高效传输函数,且无性能开销
- Babel插件集成: 自动将标记的函数转换为worklet
- 运行时创建: 为特定工作负载创建自定义JavaScript运行时
- 无缝集成: 与Reanimated无缝协作,支持动画和手势处理
文档
查看专门的文档页面,了解有关此库、API参考等的信息:https://docs.swmansion.com/react-native-worklets/(仅提供英文版)。
安装
-
在
package.json文件中添加JavaScript库依赖项。"dependencies": { ... "@amazon-devices/react-native-worklets": "~1.0.0" } - 将
@amazon-devices/react-native-worklets/plugin插件添加到babel.config.jsmodule.exports = { presets: [ ...// 请勿将其添加在此处 :) ], plugins: [ ... '@amazon-devices/react-native-worklets/plugin', ], }; - 执行
npm start -- --reset-cache命令,清理Metro bundler缓存。 - 使用
npm install命令重新安装package-lock.json文件。 - 如需更多详细信息,可参考外部文档的安装部分(仅提供英文版)。
示例
演示如何创建和使用自定义worklet运行时,以进行并行处理。
import React, { useState } from 'react';
import { Button, StyleSheet, View, Text } from 'react-native';
import { createWorkletRuntime, runOnRuntime, runOnJS } from '@amazon-devices/react-native-worklets';
/**
* 自定义Worklet运行时示例
演示如何创建和使用自定义worklet运行时,以进行并行处理。
*/
export default function WorkletCustomRuntimeExample() {
const [result, setResult] = useState<string>('');
const handlePress = () => {
setResult('Processing...');
// 使用初始化程序创建自定义运行时
const customRuntime = createWorkletRuntime('myCustomRuntime', () => {
'worklet';
console.log('自定义运行时已完成初始化!');
});
// 在自定义运行时上运行代码
runOnRuntime(customRuntime, () => {
'worklet';
console.log('在自定义运行时上运行');
// 在不阻塞用户界面或JS线程的前提下执行繁重计算
let sum = 0;
for (let i = 0; i < 1000000; i++) {
sum += i;
}
const result = `计算完成! 总和:${sum}`;
console.log(result);
runOnJS(setResult)(result);
})();
};
return (
<View style={styles.container}>
<Text style={styles.title}>自定义Worklet运行时</Text>
<Text style={styles.description}>
为特定工作负载创建独立的JavaScript运行时。
{'\n\n'}
繁重计算可并行执行,用户界面与JS线程始终畅通。
</Text>
<Button title="在自定义运行时上运行" onPress={handlePress} />
{result && <Text style={styles.result}>{result}</Text>}
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
padding: 20,
justifyContent: 'center',
},
title: {
fontSize: 24,
fontWeight: 'bold',
marginBottom: 12,
},
description: {
fontSize: 14,
color: '#666',
marginBottom: 20,
lineHeight: 20,
},
result: {
marginTop: 20,
fontSize: 16,
color: '#007AFF',
fontWeight: '500',
},
});
线程切换示例
import React, { useState } from 'react';
import { Button, StyleSheet, View, Text, ScrollView } from 'react-native';
import { runOnUI, runOnJS } from '@amazon-devices/react-native-worklets';
/**
* 线程切换示例
* 演示如何在JavaScript和用户界面线程之间切换
*/
export default function WorkletThreadSwitchExample() {
const [log, setLog] = useState<string[]>([]);
const addLog = (message: string) => {
setLog(prev => [...prev, message]);
};
const handlePress = () => {
setLog([]);
// 在JS线程上启动
addLog('1.在JS线程上启动');
// 切换到用户界面线程
runOnUI(() => {
'worklet';
console.log('2.现在位于用户界面线程上');
runOnJS(addLog)('2.现在位于用户界面线程上');
// 在用户界面线程上执行任务
const sum = Array.from({ length: 100 }, (_, i) => i).reduce((a, b) => a + b, 0);
console.log('3.在用户界面线程上计算总和:', sum);
runOnJS(addLog)(`3.计算出的总和:${sum}`);
// 回调到JS线程
runOnJS(addLog)('4.返回JS线程');
})();
};
return (
<View style={styles.container}>
<Text style={styles.title}>线程切换</Text>
<Text style={styles.description}>
演示如何通过runOnUI和runOnJS,在JavaScript和用户界面线程之间切换。
</Text>
<Button title="Switch Threads" onPress={handlePress} />
{log.length > 0 && (
<ScrollView style={styles.logContainer}>
{log.map((entry, index) => (
<Text key={index} style={styles.logEntry}>{entry}</Text>
))}
</ScrollView>
)}
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
padding: 20,
},
title: {
fontSize: 24,
fontWeight: 'bold',
marginBottom: 12,
},
description: {
fontSize: 14,
color: '#666',
marginBottom: 20,
lineHeight: 20,
},
logContainer: {
marginTop: 20,
maxHeight: 300,
padding: 12,
backgroundColor: '#f5f5f5',
borderRadius: 8,
},
logEntry: {
fontSize: 14,
color: '#333',
marginVertical: 4,
},
});
API
Vega上的Worklet库提供了全面的多线程、内存管理和实用函数API。
线程
| 方法 | 描述 |
|---|---|
createWorkletRuntime |
新建JS运行时,用于在独立线程上运行worklet |
runOnUI |
在用户界面线程(已弃用)上异步运行经worklet处理的函数 |
runOnUIAsync |
在用户界面线程上异步运行经worklet处理的函数,并返回Promise |
runOnUISync |
在用户界面线程上同步运行经worklet处理的函数,并返回结果 |
runOnJS |
在JS线程上异步运行未经worklet处理的函数(已弃用) |
runOnRuntime |
在自定义worklet运行时上运行经worklet处理的函数(已弃用) |
scheduleOnRN |
安排worklet,以在React Native (JS) 线程上运行 |
scheduleOnUI |
安排worklet,以在用户界面线程上运行 |
callMicrotasks |
处理当前运行时中所有待处理的微任务 |
executeOnUIRuntimeSync |
在用户界面运行时上同步执行代码(已弃用) |
内存
| 方法 | 描述 |
|---|---|
createSerializable |
创建一个可在不同JavaScript运行时之间传递的可序列化对象。 |
createSynchronizable |
新建一个Synchronizable对象,包含指定的初始值。 |
isSerializableRef |
检查某值是否为可序列化引用 |
isSynchronizable |
断言某个值是否为Synchronizable |
Synchronizable |
Serializable是一种共享内存类型,包含不可变值,其支持在不同JavaScript运行时之间序列化与反序列化。 |
makeShareable |
使某个值可跨线程共享(已弃用) |
makeShareableCloneRecursive |
递归克隆某个值,并使其可共享(已弃用) |
makeShareableCloneOnUIRecursive |
递归克隆某个值,并使其可在用户界面线程上共享(已弃用) |
实用工具
| 方法 | 描述 |
|---|---|
getRuntimeKind |
返回当前正在执行的运行时类型(1=JS,2=UI,3=Worker) |
isWorkletFunction |
检查某个函数是否为worklet |
Vega上的例外情况
Vega上的Worklets库在API支持方面有一些例外。此部分将介绍这些例外情况。
- Vega目前不支持Feature标记
- Vega目前不支持Bundle标记
支持的版本
| NPM程序包版本 | Vega SDK版本 | Vega OS版本 | React Native版本 |
|---|---|---|---|
| ~1.0.0 | 0.24 | 操作系统1.2 (2101020054720) |
0.83 |
Credits
该项目的构建和维护工作得到了Shopify、Expo.io和Software Mansion的支持。
Last updated: 2026年7月13日

