threejs-impl-drei

用途

threejs-impl-drei 是一个面向 React Three Fiber（R3F）使用 Drei 辅助组件时的参考技能，用于在相机控件、环境贴图、文字渲染、HTML 叠加层以及性能辅助等场景中提供正确的组件用法与注意事项，帮助避免常见错误。

主要能力

控件（Controls）：OrbitControls、CameraControls、MapControls、PresentationControls、ScrollControls、TransformControls、DragControls、KeyboardControls、FaceControls 等相机与交互控件的用法说明。
环境与布景（Environment and Staging）：Environment（预设或自定义 HDR、Lightformers）、Stage（一体化灯光与阴影）、阴影组件（ContactShadows、AccumulativeShadows、RandomizedLight、BakeShadows、SoftShadows）、大气组件（Sky、Stars、Sparkles、Cloud）。
文字与 HTML：Text（基于 troika-three-text 的 SDF 文字）、Text3D（挤压 3D 文字，需 JSON 字体）、Html（在 3D 空间中渲染 DOM）、Billboard（始终朝向相机）、Hud（独立正交场景的平视显示）。
材质（Materials）：MeshReflectorMaterial、MeshTransmissionMaterial、MeshRefractionMaterial、MeshWobbleMaterial、MeshDistortMaterial、MeshDiscardMaterial 以及 shaderMaterial 辅助方法。
加载器（Loaders）：useGLTF、useTexture、useFBX、useKTX2、useFont、useAnimations、useVideoTexture 及其 preload 用法。
性能（Performance）：Instances、Merged、Detailed（LOD）、BakeShadows、AdaptiveDpr、AdaptiveEvents、PerformanceMonitor、Bvh、meshBounds。
布景与布局：Center、Float、Bounds、Resize。
抽象与特效：Edges、Outlines、Trail、Decal、Splat、Clone、Image、MeshPortalMaterial、GradientTexture。
辅助工具（Gizmos）：GizmoHelper、PivotControls、TransformControls、Grid、Helper / useHelper。
提供组件选择指南与参考链接（references/methods.md、references/examples.md、references/anti-patterns.md 及官方来源链接）。

使用方式

安装依赖：

npm install @react-three/drei @react-three/fiber three

该技能以参考文档形式提供组件的导入方式、关键属性与可复用代码片段。例如相机控件：

import { OrbitControls } from '@react-three/drei'

<OrbitControls
  makeDefault
  enableDamping
  dampingFactor={0.05}
  minDistance={2}
  maxDistance={20}
  minPolarAngle={0}
  maxPolarAngle={Math.PI / 2}
/>

环境与模型加载示例：

import { Environment, useGLTF } from '@react-three/drei'

<Environment preset="city" background blur={0.5} />

function Model(props) {
  const { nodes, materials } = useGLTF('/model.glb')
  return (
    <group {...props}>
      <mesh geometry={nodes.Body.geometry} material={materials.Metal} />
    </group>
  )
}
useGLTF.preload('/model.glb')

滚动驱动场景示例：

import { ScrollControls, useScroll } from '@react-three/drei'

<ScrollControls pages={3} damping={0.1}>
  <ScrollScene />
</ScrollControls>

适用场景

产品查看器（Stage + OrbitControls + Environment）
建筑漫游（CameraControls + Environment + ContactShadows）
滚动叙事体验（ScrollControls + useScroll）
数据可视化（Instances + Html + Billboard）
3D 文字标签（Text / Text3D + Billboard）
玻璃或透明物体（MeshTransmissionMaterial + Environment）
反射地面（MeshReflectorMaterial）
大规模相同网格（Instances，超过 100 个）或混合几何体（Merged）
模型加载（useGLTF + Suspense + .preload()）
HUD 或叠加层（Hud 或全屏 Html）

限制与关键警告

使用加载钩子（useGLTF、useTexture、useFBX、useKTX2、useFont）的组件必须包裹在 <Suspense fallback={...}> 中，否则整个 React 树会崩溃。
主相机控件应添加 makeDefault（例如 <OrbitControls makeDefault />）；否则 Drei 控件不会与 R3F 事件系统集成，指针事件会失效。
Environment 的预设名称只能使用：apartment、city、dawn、forest、lobby、night、park、studio、sunset、warehouse。
关键资源应调用 .preload()（如模块作用域下的 useGLTF.preload('/model.glb')），以便在组件挂载前开始加载。
渲染超过 100 个相同网格时应使用 <Instances>，否则每个网格各自产生一次绘制调用。
该技能文档的具体费用、平台限制、性能数值效果等未提供，需参考官方文档确认。

官方来源

https://drei.docs.pmnd.rs/
https://github.com/pmndrs/drei
https://r3f.docs.pmnd.rs/

技能介绍

用途

主要能力

使用方式

适用场景

限制与关键警告

官方来源