React Native Reanimated Babel Plugin 完全指南Worklet 化机制、自动判定与边界限制【免费下载链接】react-native-reanimatedReact Natives Animated library reimplemented项目地址: https://gitcode.com/GitHub_Trending/re/react-native-reanimated导读本篇文章围绕 React Native Reanimated及其底层依赖 Worklets的 Babel 编译插件展开系统讲解它如何把 JavaScript 函数转换成可在 UI 线程运行的worklet从worklet指令、自动 worklet 化autoworkletization到实验性的 Worklet Context Objects、Worklet Classes再到自动化的边界与踩坑点。读完本文你将理解该插件在构建期对代码做了什么、哪些代码形态会被识别为 worklet、哪些场景必须手动标注worklet并能结合仓库源码packages/react-native-worklets/plugin/src/验证每个结论。对应文档位于 docs/docs-reanimated/versioned_docs/version-3.x/reanimated-babel-plugin/about.md配套的插件参数说明见 options.md。一、Reanimated Babel Plugin 是什么Reanimated Babel Plugin 是一段在构建期Babel 转译阶段运行的编译代码它负责把你的源码变换成可以在 UI 线程glossary 中的 ui-thread 概念执行的形态。它的核心动作是查找带有worklet;指令的函数并把它们转换成可序列化的对象这一过程在官方文档中被称为 workletization见 glossary 中的 to-workletize。也就是说当你写出下面这样一段代码function foo() { worklet; console.log(Hello from worklet); }插件会在编译阶段识别出foo是一个 worklet将其函数体捕获、序列化并在运行时注入到 UI 线程的运行时中。此后无论是 JS 线程还是 UI 线程都能执行同一份逻辑从而让动画计算、手势回调等逻辑彻底摆脱 JS 线程的瓶颈。一个 worklet 的两种来源官方文档给出了 worklet 的两种定义方式函数体顶部带worklet指令function foo() { worklet; console.log(Hello from worklet); }可以被自动 worklet 化的函数autoworkletizableuseAnimatedStyle(() { // This function will be ran on the UI thread, // hence its in a workletizable context and will be // autoworkletized. You dont need to add the worklet directive here. return { width: 100, }; });第二种形态依赖插件内置的已知回调known callback识别机制——只要函数出现在 Reanimated 规定的 API 参数位置上插件就会自动为它打上 worklet 标记无需开发者手动添加指令。说明在当前仓库中该插件的主体实现位于 packages/react-native-worklets/plugin/src/各示例应用的babel.config.js中通过react-native-worklets/plugin引用它见 apps/fabric-example/babel.config.js。本文所引源码路径均以仓库根目录为基准。二、什么可以成为 Worklet并非所有函数都会被插件处理官方文档把可 worklet 化的对象分成两大类JavaScript 语法层面的术语以及Reanimated 特有的术语。2.1 JavaScript 术语JavaScript terms插件支持以下四种 JS 语法形态作为 worklet函数声明Function Declarationfunction foo() { worklet; console.log(Hello from FunctionDeclaration); }函数表达式Function Expressionconst foo function () { worklet; console.log(Hello from FunctionExpression); };箭头函数表达式Arrow Function Expressionconst foo () { worklet; console.log(Hello from ArrowFunctionExpression); };对象方法Object Methodconst obj { foo() { worklet; console.log(Hello from ObjectMethod); }, };从源码结构看这四种形态被统一抽象为插件内部的WorkletizableFunction类型函数声明、函数表达式、箭头函数、对象方法均被归入该联合类型插件在 visitor 中对该类型统一注册了处理逻辑见 packages/react-native-worklets/plugin/src/plugin.ts 与 packages/react-native-worklets/plugin/src/types.ts。2.2 Reanimated 术语Reanimated terms[实验性] Worklet Context ObjectsUI 线程上调用对象方法时其this绑定会丢失。例如const obj { foo: 1, bar() { worklet; console.log(this.foo); // undefined - the binding was lost. }, };Worklet Context Objects是为此设计的特殊术语它可以保留this绑定。注意不要把它和useSharedValue创建的对象混淆——Worklet Context Objects 在 UI 线程上的所有修改只对 UI 线程可见JS 线程上的修改同理两个线程之间不会同步const obj { __workletContextObject: true, foo: 1, bar() { console.log(this.foo); }, }; obj.foo 2; obj.bar(); // Logs 2 runOnUI(() obj.bar())(); // Logs 1 runOnUI(() (obj.foo 3))(); obj.bar(); // Logs 2 runOnUI(() obj.bar())(); // Logs 3__workletContextObject是标记一个对象为 Worklet Context Object 的特殊属性它的值不重要但实践中建议使用true。一旦对象带有该属性其方法内部的worklet指令会被忽略const workletContextObject { __workletContextObject: true, message: Hello from WorkletContextObject, foo() { console.log(this.message); }, };[实验性] Worklet ClassesReact Native 使用的 JavaScript 引擎 Hermes 原生不支持 class 语法class 需要经过 polyfill 才能在 UI 线程运行这带来了额外复杂度。为此插件提出了Worklet Classes术语被标记的 class 可以在 UI 线程上被实例化。__workletClass是标记一个 class 为 Worklet Class 的特殊属性值同样不重要建议使用true带有该属性的 class其方法内的worklet指令会被忽略class Clazz { __workletClass true; message Hello from WorkletClass; foo() { console.log(this.message); } } runOnUI(() new Clazz().foo())(); // Logs Hello from WorkletClass已知限制PitfallsWorklet Classes 不支持静态方法和静态属性class 实例不能跨 JS / UI 线程共享。源码层面的实现印证Worklet Class 的处理入口是 packages/react-native-worklets/plugin/src/class.ts 中的processIfWorkletClass。它检测类体中是否包含__workletClass标记hasWorkletClassMarker随后把 class 代码交给babel/plugin-transform-class-properties、babel/plugin-transform-classes等插件做 polyfill再对 polyfill 生成的所有函数声明追加 worklet 指令appendWorkletDirectiveToPolyfills最后将整个 class 声明替换为工厂函数 立即调用的结构replaceClassDeclarationWithFactoryAndCall从而保证 class 实例化逻辑本身也能作为 worklet 在 UI 线程执行。此外插件在 plugin.ts 的ClassDeclarationvisitor 中还支持通过disableWorkletClasses选项关闭该功能。三、自动 Worklet 化Autoworkletization为了减少样板代码并提供更安全的 API插件会自动判断一个函数是否应当被 worklet 化因此你不需要为所有回调手动添加worklet指令const style useAnimatedStyle(() { // You dont need to add the worklet directive here, // since plugin detects this callback as autoworkletizable. return { width: 100, }; });这一能力并不局限于useAnimatedStyle——插件会对 Reanimated 全部 API 的回调做自动 worklet 化。完整的 API 清单可以在 packages/react-native-worklets/plugin/src/autoworkletization.ts 中查看函数型 Hook/APIuseFrameCallback、useAnimatedStyle、useAnimatedProps、createAnimatedPropAdapter、useDerivedValue、useAnimatedScrollHandler、useAnimatedReaction第 0、1 两个参数都会被处理等动画回调withTiming第 2 个参数、withSpring第 2 个参数、withDecay第 1 个参数、withRepeat第 3 个参数等调度函数runOnUI、runOnUISync、scheduleOnUI、runOnRuntime、scheduleOnRuntime及其 Async/Sync 变体等手势相关useAnimatedScrollHandler以及来自gestureHandlerObjectHooks的对象型手势 Hook、gestureHandlerBuilderMethods中的 builder 方法定义见同目录下的 gestureHandlerAutoworkletization.ts。每个 API 具体 worklet 化哪个参数由reanimatedFunctionArgsToWorkletize这个映射表参数索引数组精确控制匹配过程则通过 findWorklet.ts 中的findWorklet/forEachWorkletizableFunction递归地在实参 AST 节点上查找可 worklet 化的函数或对象。在高级用法中你仍可能需要手动把函数标记为 worklet这一点官方文档也有明确提醒。3.1 引用传递引用的 worklet你可以在使用位置之前定义 worklet插件同样会自动 worklet 化它function foo() { // You dont need to add // the worklet directive here. return { width: 100 }; } // You dont need to define an inline function here, // a reference is enough. const style useAnimatedStyle(foo);这正是findWorklet中nodePath.isIdentifier() nodePath.isReferencedIdentifier()分支所承担的工作——当实参是一个被引用的标识符时插件会沿作用域回溯找到它的定义节点见 findWorklet.ts 及 referencedWorklets.ts再对该定义执行 worklet 化。3.2 聚合 worklet 的对象Objects aggregating worklets某些 API如useAnimatedScrollHandler接受一个包含多个 worklet 方法的对象而不是单个函数const handlerObject { // You dont need to mark these methods as worklets. onBeginDrag() { console.log(Dragging...); }, onScroll() { console.log(Scrolling...); }, }; const handler useAnimatedScrollHandler(handlerObject);对象中每个方法都会被自动 worklet 化。useAnimatedScrollHandler同时被列入函数型与对象型 Hook 集合见 autoworkletization.tsforEachWorkletizableObjectProperty会遍历对象的所有属性对象方法ObjectMethod直接处理对象属性ObjectProperty则继续递归检查其值findWorklet.ts。3.3 [实验性] 整个文件 worklet 化可以在文件顶部添加worklet;指令把整个文件标记为可 worklet 化文件。插件会为文件中所有顶层的 JavaScript 术语和 Reanimated 术语自动 worklet 化适合包含大量 worklet 的工具文件// file.ts worklet; function foo() { // Function foo will be autoworkletized. return { width: 100 }; } function bar() { // Function bar will be autoworkletized. function foobar() { // Function foobar wont since its not defined in top-level scope. console.log(Im not a worklet); } return { width: 100 }; }注意只有顶层作用域中的实体才会被处理嵌套函数如bar内部的foobar不会被自动 worklet 化。源码印证文件级处理实现在 packages/react-native-worklets/plugin/src/file.ts 的processIfWorkletFile中——它先检查Program节点是否存在值为worklet的指令若有则移除该指令再遍历顶层语句函数声明/表达式被追加 worklet 指令对象字面量递归处理其属性VariableDeclaration递归处理其初始化表达式ClassDeclaration则追加__workletClass标记并入队等待处理。插件还贴心地对 CommonJS 的exports.xxx ...语句做了去提升dehoistCommonJSExports避免它们干扰顶层遍历。四、自动 Worklet 化的边界插件无法在所有上下文中判断一个函数是否应当被 worklet 化以下是三个典型边界场景。4.1 跨文件导入Imports从其他文件或模块导入函数并用作 worklet 时必须手动添加worklet指令// foo.ts import { bar } from ./bar; // ... const style useAnimatedStyle(bar); // bar.ts export function bar() { worklet; // Wont work without it. return { width: 100, }; }原因在于自动 worklet 化依赖对实参表达式与同作用域定义的分析跨模块的导入无法在单个文件内完成可靠回溯因此需要开发者显式标注。4.2 自定义 HookCustom hooks目前 Reanimated 尚未暴露允许开发者注册自定义 Hook 回调 worklet 化的 API。也就是说如果你自己封装了一个接收回调函数的 Hook其回调不会获得自动 worklet 化需要手动添加指令。不过官方文档提到这一限制未来可能会改变。4.3 表达式Expressions当函数是某个表达式的结果时它不会自动 worklet 化必须显式加worklet;const foo someCondition ? () { worklet; // Wont work without it. return { width: 100 }; } : () { worklet; // Wont work without it. return { width: 200 }; }; const style useAnimatedStyle(foo);对于这种场景官方文档的建议是要么在 worklet 内部处理条件逻辑要么重构代码以消除条件 worklet 的需要。补充说明从实现细节看插件的自动 worklet 化微插件micro-plugin在pre阶段对整个文件做一次额外的 AST 遍历见 plugin.ts它按CallExpression已知 API 调用→WorkletizableFunction给已知回调补指令→Directive处理worklet指令并附带注入use no memo见 directives.ts的顺序工作。这也解释了为什么条件表达式、跨模块引用这类无法静态确定实参形态的写法会落在自动化的覆盖范围之外。五、已知陷阱Worklet 不会被提升Hoisting存在一些与插件不兼容的写法官方文档重点提示了worklet 不会被提升hoisted// The following line crashes, // even though foo is marked as a worklet. const style useAnimatedStyle(foo); function foo() { worklet; return { width: 100 }; }上面这段代码会崩溃。尽管foo被标记为 worklet但由于在使用之前才定义插件在分析useAnimatedStyle(foo)时还无法为foo生成 worklet 数据运行时便会失败。正确的做法是像 3.1 节那样先定义、后引用。与之配套的还有directives.ts中的一个细节对于箭头函数如果其函数体是隐式返回表达式如() 1插件会先把它改写成带块语句的形式() { return 1 }因为指令只能存在于块语句函数体上见 directives.ts 的addWorkletDirectivesToPath与replaceImplicitReturnWithBlock。六、插件运行机制速览源码级为便于深入排查问题这里汇总插件主流程的关键入口均位于 packages/react-native-worklets/plugin/src/处理内容入口文件与函数说明插件整体入口与 visitor 注册plugin.ts注册CallExpression、WorkletizableFunction、ClassDeclaration、ClassMethod、Program、ExpressionStatement、JSXAttribute等 visitor自动 worklet 化微插件plugin.tsgetAutoworkletizationMicroPlugin在pre阶段先于 React Compiler 运行为已知回调补指令已知回调清单autoworkletization.tsreanimatedFunctionHooks/reanimatedObjectHooks/reanimatedFunctionArgsToWorkletizeworklet 查找findWorklet.ts实参 AST 上的函数/对象递归匹配指令注入directives.ts注入worklet与use no memo改写箭头函数隐式返回文件级 worklet 化file.ts顶层实体批量 worklet 化Worklet Class 处理class.tsclass polyfill 工厂函数替换类方法处理classMethod.ts将带 worklet 指令的方法重写为类属性函数表达式默认白名单全局标识符globals.tsglobalThis、Infinity、NaN、undefined、Object、Array、Map等不会被捕获复制到 UI 线程其中globals.ts中列出的是一批无需捕获的全局标识符worklet 闭包引用到它们时插件不会把它们的值复制到 UI 线程因为 UI 线程运行时本身就存在这些全局对象见 packages/react-native-worklets/plugin/src/globals.ts。七、与插件选项Options的关系本文所述的行为大部分可通过插件选项微调例如processNestedWorklets实验性多线程嵌套 worklet 支持、disableInlineStylesWarning关闭内联共享值警告、omitNativeOnlyData/substituteWebPlatformChecksWeb 端瘦身、globals追加白名单标识符等。完整的参数说明与babel.config.js配置示例见同目录下的 options.md其 TypeScript 类型定义位于 packages/react-native-worklets/plugin/src/options.ts仓库内各示例应用如 apps/fabric-example/babel.config.js、apps/web-example/babel.config.js也提供了真实可用的配置范本。八、总结Reanimated Babel Plugin 是 Reanimated 能在 UI 线程运行动画逻辑的关键构建期组件。理解它的核心结论可归纳为两种 worklet 来源显式worklet指令函数声明、函数表达式、箭头函数、对象方法以及自动 worklet 化Reanimated 已知 API 的回调。两个实验性术语Worklet Context Objects保留this绑定、线程间不共享与 Worklet ClassesHermes 下的 class 变通方案分别以__workletContextObject和__workletClass标记。三类自动化边界跨文件导入、自定义 Hook、条件表达式结果均需手动worklet指令。一条硬性规则worklet 不会被提升必须先定义、后使用。查证路径所有自动 worklet 化的 API 清单与实现细节均可在 packages/react-native-worklets/plugin/src/autoworkletization.ts 等源码文件中逐条核对。【免费下载链接】react-native-reanimatedReact Natives Animated library reimplemented项目地址: https://gitcode.com/GitHub_Trending/re/react-native-reanimated创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
React Native Reanimated Babel Plugin 完全指南：Worklet 化机制、自动判定与边界限制
React Native Reanimated Babel Plugin 完全指南Worklet 化机制、自动判定与边界限制【免费下载链接】react-native-reanimatedReact Natives Animated library reimplemented项目地址: https://gitcode.com/GitHub_Trending/re/react-native-reanimated导读本篇文章围绕 React Native Reanimated及其底层依赖 Worklets的 Babel 编译插件展开系统讲解它如何把 JavaScript 函数转换成可在 UI 线程运行的worklet从worklet指令、自动 worklet 化autoworkletization到实验性的 Worklet Context Objects、Worklet Classes再到自动化的边界与踩坑点。读完本文你将理解该插件在构建期对代码做了什么、哪些代码形态会被识别为 worklet、哪些场景必须手动标注worklet并能结合仓库源码packages/react-native-worklets/plugin/src/验证每个结论。对应文档位于 docs/docs-reanimated/versioned_docs/version-3.x/reanimated-babel-plugin/about.md配套的插件参数说明见 options.md。一、Reanimated Babel Plugin 是什么Reanimated Babel Plugin 是一段在构建期Babel 转译阶段运行的编译代码它负责把你的源码变换成可以在 UI 线程glossary 中的 ui-thread 概念执行的形态。它的核心动作是查找带有worklet;指令的函数并把它们转换成可序列化的对象这一过程在官方文档中被称为 workletization见 glossary 中的 to-workletize。也就是说当你写出下面这样一段代码function foo() { worklet; console.log(Hello from worklet); }插件会在编译阶段识别出foo是一个 worklet将其函数体捕获、序列化并在运行时注入到 UI 线程的运行时中。此后无论是 JS 线程还是 UI 线程都能执行同一份逻辑从而让动画计算、手势回调等逻辑彻底摆脱 JS 线程的瓶颈。一个 worklet 的两种来源官方文档给出了 worklet 的两种定义方式函数体顶部带worklet指令function foo() { worklet; console.log(Hello from worklet); }可以被自动 worklet 化的函数autoworkletizableuseAnimatedStyle(() { // This function will be ran on the UI thread, // hence its in a workletizable context and will be // autoworkletized. You dont need to add the worklet directive here. return { width: 100, }; });第二种形态依赖插件内置的已知回调known callback识别机制——只要函数出现在 Reanimated 规定的 API 参数位置上插件就会自动为它打上 worklet 标记无需开发者手动添加指令。说明在当前仓库中该插件的主体实现位于 packages/react-native-worklets/plugin/src/各示例应用的babel.config.js中通过react-native-worklets/plugin引用它见 apps/fabric-example/babel.config.js。本文所引源码路径均以仓库根目录为基准。二、什么可以成为 Worklet并非所有函数都会被插件处理官方文档把可 worklet 化的对象分成两大类JavaScript 语法层面的术语以及Reanimated 特有的术语。2.1 JavaScript 术语JavaScript terms插件支持以下四种 JS 语法形态作为 worklet函数声明Function Declarationfunction foo() { worklet; console.log(Hello from FunctionDeclaration); }函数表达式Function Expressionconst foo function () { worklet; console.log(Hello from FunctionExpression); };箭头函数表达式Arrow Function Expressionconst foo () { worklet; console.log(Hello from ArrowFunctionExpression); };对象方法Object Methodconst obj { foo() { worklet; console.log(Hello from ObjectMethod); }, };从源码结构看这四种形态被统一抽象为插件内部的WorkletizableFunction类型函数声明、函数表达式、箭头函数、对象方法均被归入该联合类型插件在 visitor 中对该类型统一注册了处理逻辑见 packages/react-native-worklets/plugin/src/plugin.ts 与 packages/react-native-worklets/plugin/src/types.ts。2.2 Reanimated 术语Reanimated terms[实验性] Worklet Context ObjectsUI 线程上调用对象方法时其this绑定会丢失。例如const obj { foo: 1, bar() { worklet; console.log(this.foo); // undefined - the binding was lost. }, };Worklet Context Objects是为此设计的特殊术语它可以保留this绑定。注意不要把它和useSharedValue创建的对象混淆——Worklet Context Objects 在 UI 线程上的所有修改只对 UI 线程可见JS 线程上的修改同理两个线程之间不会同步const obj { __workletContextObject: true, foo: 1, bar() { console.log(this.foo); }, }; obj.foo 2; obj.bar(); // Logs 2 runOnUI(() obj.bar())(); // Logs 1 runOnUI(() (obj.foo 3))(); obj.bar(); // Logs 2 runOnUI(() obj.bar())(); // Logs 3__workletContextObject是标记一个对象为 Worklet Context Object 的特殊属性它的值不重要但实践中建议使用true。一旦对象带有该属性其方法内部的worklet指令会被忽略const workletContextObject { __workletContextObject: true, message: Hello from WorkletContextObject, foo() { console.log(this.message); }, };[实验性] Worklet ClassesReact Native 使用的 JavaScript 引擎 Hermes 原生不支持 class 语法class 需要经过 polyfill 才能在 UI 线程运行这带来了额外复杂度。为此插件提出了Worklet Classes术语被标记的 class 可以在 UI 线程上被实例化。__workletClass是标记一个 class 为 Worklet Class 的特殊属性值同样不重要建议使用true带有该属性的 class其方法内的worklet指令会被忽略class Clazz { __workletClass true; message Hello from WorkletClass; foo() { console.log(this.message); } } runOnUI(() new Clazz().foo())(); // Logs Hello from WorkletClass已知限制PitfallsWorklet Classes 不支持静态方法和静态属性class 实例不能跨 JS / UI 线程共享。源码层面的实现印证Worklet Class 的处理入口是 packages/react-native-worklets/plugin/src/class.ts 中的processIfWorkletClass。它检测类体中是否包含__workletClass标记hasWorkletClassMarker随后把 class 代码交给babel/plugin-transform-class-properties、babel/plugin-transform-classes等插件做 polyfill再对 polyfill 生成的所有函数声明追加 worklet 指令appendWorkletDirectiveToPolyfills最后将整个 class 声明替换为工厂函数 立即调用的结构replaceClassDeclarationWithFactoryAndCall从而保证 class 实例化逻辑本身也能作为 worklet 在 UI 线程执行。此外插件在 plugin.ts 的ClassDeclarationvisitor 中还支持通过disableWorkletClasses选项关闭该功能。三、自动 Worklet 化Autoworkletization为了减少样板代码并提供更安全的 API插件会自动判断一个函数是否应当被 worklet 化因此你不需要为所有回调手动添加worklet指令const style useAnimatedStyle(() { // You dont need to add the worklet directive here, // since plugin detects this callback as autoworkletizable. return { width: 100, }; });这一能力并不局限于useAnimatedStyle——插件会对 Reanimated 全部 API 的回调做自动 worklet 化。完整的 API 清单可以在 packages/react-native-worklets/plugin/src/autoworkletization.ts 中查看函数型 Hook/APIuseFrameCallback、useAnimatedStyle、useAnimatedProps、createAnimatedPropAdapter、useDerivedValue、useAnimatedScrollHandler、useAnimatedReaction第 0、1 两个参数都会被处理等动画回调withTiming第 2 个参数、withSpring第 2 个参数、withDecay第 1 个参数、withRepeat第 3 个参数等调度函数runOnUI、runOnUISync、scheduleOnUI、runOnRuntime、scheduleOnRuntime及其 Async/Sync 变体等手势相关useAnimatedScrollHandler以及来自gestureHandlerObjectHooks的对象型手势 Hook、gestureHandlerBuilderMethods中的 builder 方法定义见同目录下的 gestureHandlerAutoworkletization.ts。每个 API 具体 worklet 化哪个参数由reanimatedFunctionArgsToWorkletize这个映射表参数索引数组精确控制匹配过程则通过 findWorklet.ts 中的findWorklet/forEachWorkletizableFunction递归地在实参 AST 节点上查找可 worklet 化的函数或对象。在高级用法中你仍可能需要手动把函数标记为 worklet这一点官方文档也有明确提醒。3.1 引用传递引用的 worklet你可以在使用位置之前定义 worklet插件同样会自动 worklet 化它function foo() { // You dont need to add // the worklet directive here. return { width: 100 }; } // You dont need to define an inline function here, // a reference is enough. const style useAnimatedStyle(foo);这正是findWorklet中nodePath.isIdentifier() nodePath.isReferencedIdentifier()分支所承担的工作——当实参是一个被引用的标识符时插件会沿作用域回溯找到它的定义节点见 findWorklet.ts 及 referencedWorklets.ts再对该定义执行 worklet 化。3.2 聚合 worklet 的对象Objects aggregating worklets某些 API如useAnimatedScrollHandler接受一个包含多个 worklet 方法的对象而不是单个函数const handlerObject { // You dont need to mark these methods as worklets. onBeginDrag() { console.log(Dragging...); }, onScroll() { console.log(Scrolling...); }, }; const handler useAnimatedScrollHandler(handlerObject);对象中每个方法都会被自动 worklet 化。useAnimatedScrollHandler同时被列入函数型与对象型 Hook 集合见 autoworkletization.tsforEachWorkletizableObjectProperty会遍历对象的所有属性对象方法ObjectMethod直接处理对象属性ObjectProperty则继续递归检查其值findWorklet.ts。3.3 [实验性] 整个文件 worklet 化可以在文件顶部添加worklet;指令把整个文件标记为可 worklet 化文件。插件会为文件中所有顶层的 JavaScript 术语和 Reanimated 术语自动 worklet 化适合包含大量 worklet 的工具文件// file.ts worklet; function foo() { // Function foo will be autoworkletized. return { width: 100 }; } function bar() { // Function bar will be autoworkletized. function foobar() { // Function foobar wont since its not defined in top-level scope. console.log(Im not a worklet); } return { width: 100 }; }注意只有顶层作用域中的实体才会被处理嵌套函数如bar内部的foobar不会被自动 worklet 化。源码印证文件级处理实现在 packages/react-native-worklets/plugin/src/file.ts 的processIfWorkletFile中——它先检查Program节点是否存在值为worklet的指令若有则移除该指令再遍历顶层语句函数声明/表达式被追加 worklet 指令对象字面量递归处理其属性VariableDeclaration递归处理其初始化表达式ClassDeclaration则追加__workletClass标记并入队等待处理。插件还贴心地对 CommonJS 的exports.xxx ...语句做了去提升dehoistCommonJSExports避免它们干扰顶层遍历。四、自动 Worklet 化的边界插件无法在所有上下文中判断一个函数是否应当被 worklet 化以下是三个典型边界场景。4.1 跨文件导入Imports从其他文件或模块导入函数并用作 worklet 时必须手动添加worklet指令// foo.ts import { bar } from ./bar; // ... const style useAnimatedStyle(bar); // bar.ts export function bar() { worklet; // Wont work without it. return { width: 100, }; }原因在于自动 worklet 化依赖对实参表达式与同作用域定义的分析跨模块的导入无法在单个文件内完成可靠回溯因此需要开发者显式标注。4.2 自定义 HookCustom hooks目前 Reanimated 尚未暴露允许开发者注册自定义 Hook 回调 worklet 化的 API。也就是说如果你自己封装了一个接收回调函数的 Hook其回调不会获得自动 worklet 化需要手动添加指令。不过官方文档提到这一限制未来可能会改变。4.3 表达式Expressions当函数是某个表达式的结果时它不会自动 worklet 化必须显式加worklet;const foo someCondition ? () { worklet; // Wont work without it. return { width: 100 }; } : () { worklet; // Wont work without it. return { width: 200 }; }; const style useAnimatedStyle(foo);对于这种场景官方文档的建议是要么在 worklet 内部处理条件逻辑要么重构代码以消除条件 worklet 的需要。补充说明从实现细节看插件的自动 worklet 化微插件micro-plugin在pre阶段对整个文件做一次额外的 AST 遍历见 plugin.ts它按CallExpression已知 API 调用→WorkletizableFunction给已知回调补指令→Directive处理worklet指令并附带注入use no memo见 directives.ts的顺序工作。这也解释了为什么条件表达式、跨模块引用这类无法静态确定实参形态的写法会落在自动化的覆盖范围之外。五、已知陷阱Worklet 不会被提升Hoisting存在一些与插件不兼容的写法官方文档重点提示了worklet 不会被提升hoisted// The following line crashes, // even though foo is marked as a worklet. const style useAnimatedStyle(foo); function foo() { worklet; return { width: 100 }; }上面这段代码会崩溃。尽管foo被标记为 worklet但由于在使用之前才定义插件在分析useAnimatedStyle(foo)时还无法为foo生成 worklet 数据运行时便会失败。正确的做法是像 3.1 节那样先定义、后引用。与之配套的还有directives.ts中的一个细节对于箭头函数如果其函数体是隐式返回表达式如() 1插件会先把它改写成带块语句的形式() { return 1 }因为指令只能存在于块语句函数体上见 directives.ts 的addWorkletDirectivesToPath与replaceImplicitReturnWithBlock。六、插件运行机制速览源码级为便于深入排查问题这里汇总插件主流程的关键入口均位于 packages/react-native-worklets/plugin/src/处理内容入口文件与函数说明插件整体入口与 visitor 注册plugin.ts注册CallExpression、WorkletizableFunction、ClassDeclaration、ClassMethod、Program、ExpressionStatement、JSXAttribute等 visitor自动 worklet 化微插件plugin.tsgetAutoworkletizationMicroPlugin在pre阶段先于 React Compiler 运行为已知回调补指令已知回调清单autoworkletization.tsreanimatedFunctionHooks/reanimatedObjectHooks/reanimatedFunctionArgsToWorkletizeworklet 查找findWorklet.ts实参 AST 上的函数/对象递归匹配指令注入directives.ts注入worklet与use no memo改写箭头函数隐式返回文件级 worklet 化file.ts顶层实体批量 worklet 化Worklet Class 处理class.tsclass polyfill 工厂函数替换类方法处理classMethod.ts将带 worklet 指令的方法重写为类属性函数表达式默认白名单全局标识符globals.tsglobalThis、Infinity、NaN、undefined、Object、Array、Map等不会被捕获复制到 UI 线程其中globals.ts中列出的是一批无需捕获的全局标识符worklet 闭包引用到它们时插件不会把它们的值复制到 UI 线程因为 UI 线程运行时本身就存在这些全局对象见 packages/react-native-worklets/plugin/src/globals.ts。七、与插件选项Options的关系本文所述的行为大部分可通过插件选项微调例如processNestedWorklets实验性多线程嵌套 worklet 支持、disableInlineStylesWarning关闭内联共享值警告、omitNativeOnlyData/substituteWebPlatformChecksWeb 端瘦身、globals追加白名单标识符等。完整的参数说明与babel.config.js配置示例见同目录下的 options.md其 TypeScript 类型定义位于 packages/react-native-worklets/plugin/src/options.ts仓库内各示例应用如 apps/fabric-example/babel.config.js、apps/web-example/babel.config.js也提供了真实可用的配置范本。八、总结Reanimated Babel Plugin 是 Reanimated 能在 UI 线程运行动画逻辑的关键构建期组件。理解它的核心结论可归纳为两种 worklet 来源显式worklet指令函数声明、函数表达式、箭头函数、对象方法以及自动 worklet 化Reanimated 已知 API 的回调。两个实验性术语Worklet Context Objects保留this绑定、线程间不共享与 Worklet ClassesHermes 下的 class 变通方案分别以__workletContextObject和__workletClass标记。三类自动化边界跨文件导入、自定义 Hook、条件表达式结果均需手动worklet指令。一条硬性规则worklet 不会被提升必须先定义、后使用。查证路径所有自动 worklet 化的 API 清单与实现细节均可在 packages/react-native-worklets/plugin/src/autoworkletization.ts 等源码文件中逐条核对。【免费下载链接】react-native-reanimatedReact Natives Animated library reimplemented项目地址: https://gitcode.com/GitHub_Trending/re/react-native-reanimated创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
