SuperAPI AI 工具集

react-three-fiber

编程与开发

查看项目

更新于 11-04 18:33

技能介绍

React Three Fiber(R3F)是 three.js 的 React 渲染器,包名为 @react-three/fiber。本技能是一份围绕该库组织的参考文档集,资料针对版本 9.8.2(npm latest 9.8.2,GitHub tag v9.8.2,commit d74622ea8ed717f7212d7e19d65ff3e325508389),并说明同版本附带 @react-three/test-renderer 9.1.1 与 @react-three/eslint-plugin 0.1.2,资料获取日期为 2026-10-17。资料同时提示:tag 时点的 package.json 与 CHANGELOG 仍停留在 9.8.1,9.8.2 的变更仅见于 GitHub Release 正文;官方文档站点根路径与 tag 一致,站点的 /next 属于 v10 alpha,不建议参照,v10.0.0-alpha.5 与 canary 均未收录。

用途上,该技能用于在开发 R3F 应用时快速查阅 API 与用法。文档按主题分为若干目录,每个目录含 README.md 作为索引,再指向具体页面,整体结构为:skills/react-three-fiber/SKILL.md,以及 references 下的 getting-started、canvas、hooks、objects、events、exports、performance、testing-tooling、typescript 各分类,另有 samples 与 scripts 目录。

各分类的主要内容如下。getting-started 覆盖简介、安装、工作原理、React Native 以及 v9 迁移指南。canvas 覆盖 Canvas 的 props、createRoot 创建自定义 root、默认值、错误与回退、渲染器替换、tree-shaking、配置更新与 WebGPU。hooks 覆盖 RootState、useFrame、useGraph、useInstanceHandle、useLoader、useThree。objects 覆盖用 JSX 声明 three.js 对象,以及 attach、构造参数、disposal、嵌套属性穿透、primitive、shader-material uniforms、快捷写法与第三方对象。events 覆盖自定义事件、事件数据、事件处理器、事件传播、event target 与 prefix、pointer capture、无交互的 raycast。exports 覆盖 act、addEffect、advance、applyProps、buildGraph、createPortal、events、extend、flushSync、invalidate 等导出。performance 覆盖并发、实例化、LOD、movement regression、嵌套加载、按需渲染、性能监控,以及挂载与对象、状态与循环方面的常见陷阱,还有几何体与材质复用。testing-tooling 覆盖 ESLint 插件及 no-clone-in-loop、no-new-in-loop 两条规则,以及 test-renderer 的 create、act、fireEvent、生命周期与场景图。typescript 覆盖导出类型、扩展类型、扩展默认元素、three 元素与 useRef 类型标注。samples 提供基础动画、基础示例、事件与交互、加载 glTF 模型、加载 OBJ/FBX/STL 模型、加载进度、加载纹理、使用 test-renderer 测试与第一个场景等示例说明。scripts 覆盖安装、React Native 与工具相关命令。

使用方式上,资料建议按任务定位:先在下述映射表找到任务对应分类,再阅读该分类的 references/{category}/README.md 确定具体页面,最后读取对应 .md 文件。映射关系为:R3F 概览、工作原理与 v8 到 v9 迁移对应 getting-started;Canvas props、createRoot、WebGPU、渲染器替换对应 canvas;useFrame/useThree/useLoader/RootState 对应 hooks;three.js 对象的 JSX 声明、attach、args、primitive、dispose 对应 objects;指针事件、传播、pointer capture、event target 对应 events;extend/invalidate/advance/createPortal/applyProps 等导出对应 exports;按需渲染、实例化、LOD 与陷阱等性能议题对应 performance;test-renderer 测试与 ESLint 规则对应 testing-tooling;ThreeElements 类型扩展、useRef 类型标注与公开类型对应 typescript;首个场景、动画、模型加载等典型用法对应 samples;安装、React Native 与工具命令对应 scripts。

适用场景主要是使用 React 构建 three.js 三维场景、动画、模型与纹理加载、事件交互、性能优化和组件测试的开发者,以及需要为 R3F 组件补充 TypeScript 类型的项目。

限制方面,资料明确 three.js 本体类 API(geometry/material/loader/renderer)由 threejs 技能负责,@theatre/r3f 由 theatrejs 技能负责;@react-three/drei 是独立包,未收录;v10 alpha 与 canary 未收录。除上述版本与目录信息外,该技能的安装命令、代码示例细节、收费与平台支持等在资料中未完整给出,暂未提供。