as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
Ring
AWS
文档
Support
Contact Us
My Cases
新手入门
设计和开发
应用发布
参考
支持

react-native-worklets

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/(仅提供英文版)。

安装

  1. package.json文件中添加JavaScript库依赖项。

    已复制到剪贴板。

    "dependencies": {
         ...
         "@amazon-devices/react-native-worklets": "~1.0.0"
    }
    
  2. @amazon-devices/react-native-worklets/plugin插件添加到babel.config.js
     module.exports = {
       presets: [
         ...// 请勿将其添加在此处 :)
       ],
       plugins: [
         ...
         '@amazon-devices/react-native-worklets/plugin',
       ],
     };
    
  3. 执行npm start -- --reset-cache命令,清理Metro bundler缓存。
  4. 使用npm install命令重新安装package-lock.json文件。
  5. 如需更多详细信息,可参考外部文档的安装部分(仅提供英文版)。

示例

演示如何创建和使用自定义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

该项目的构建和维护工作得到了ShopifyExpo.ioSoftware Mansion的支持。


Last updated: 2026年7月13日