SuperAPI AI 工具集

r3f-loaders

前端与建站

查看项目

更新于 10-15 21:38

技能介绍

用途:在 React Three Fiber 中加载与复用 3D 资源,覆盖模型加载、解码器设置、缓存、克隆等场景。使用前先检查已安装的 Fiber、Drei、Three.js 与 React 版本,示例基于 Fiber 9 / React 19;需核实真实资源路径、节点名、格式与压缩方式,不要臆造模型结构。

主要能力:glTF/GLB 优先用 useGLTF,其他格式用 useLoader 配对应 Three.js 加载器;Fiber 9 也接受外部持有的加载器实例以隔离配置。加载器钩子会挂起,需用 Suspense 边界:应同时出现的资源放同一边界,独立加载的用不同边界;可预加载可能需要的资源,但预加载只发起请求,不保证即时显示或着色器编译完成。条件加载应条件挂载调用钩子的子组件,不要传 null 或条件调用钩子。Three.js 插件路径如 three/addons/loaders/GLTFLoader.js,注意新版用 HDRLoader 替代旧例中的 RGBELoader。

缓存与克隆:缓存结果视为共享,同一 Object3D 挂到两个父级会移动而非复制,重复摆放需克隆图。Drei Clone 支持普通复制与骨骼感知克隆;独立动画混合器宜用 SkeletonUtils.clone 明确归属。图克隆通常共享几何、纹理与材质,逐实例修改前先克隆对应材质/纹理,避免整体深拷贝浪费内存。用 dispose={null} 防止单个消费者释放共享缓存资源;Primitives 不会被 R3F 自动释放,useGLTF.clear 与 useLoader.clear 都不是完整 GPU 清理。不要在渲染中清缓存,也不要为局部设置改动缓存场景的变换或材质。

解码与失败路径:useGLTF 集成 Draco/Meshopt,但解码器 URL 与加载器配置须匹配资源与托管策略;KTX2 纹理需先配置带渲染器能力检测的 KTX2Loader。预加载与实际加载用相同设置,且须在请求前配置。避免每次渲染新建解码器工作池。Suspense 不处理被拒请求,需错误边界与明确重试策略。Canvas 内用 Three.js 回退或 Drei Html,Drei Loader 属 DOM 覆盖层应放在 Canvas 外。useProgress 反映加载管理器活动,未必是单资源精确进度。需测试网络错误、CORS、解码器托管与真实压缩资源。