# 反应三纤维 React Three Fiber (R3F) 是 Three.js 的 React 渲染器。使用 JSX 编写声明性的、基于组件的 3D 场景。 > **库版本 (2026)** > > * 反应三纤维：v9.5+ > * @react-三/drei: v9.116+ > * @react-三/剑杆：v2+ > * @react-三/后处理：v3+ > * React：19+（支持并发功能） > ## 决策框架 ### 何时使用 R3F 与 Vanilla Three.js 您的应用程序已经基于 React 了吗？ → 是：使用 R3F（自然集成） → 否：考虑普通 Three.js 你需要 React 状态管理吗？ → 是：使用 R3F（无缝状态集成） → 否：两者都有效 3D 场景是整个应用程序吗？ → 是：两者都可以（R3F 有轻微的开销） → 不，与 React UI 混合：使用 R3F 数以百万计的对象对性能至关重要？ → 考虑使用普通 Three.js 以获得最大程度的控制 → R3F 适用于 99% 的用例 ### 何时使用哪种状态管理本地组件状态（单一网格颜色，悬停）？ → useState / useRef 在几个组件（选定的对象）之间共享？ → React Context 或 prop 钻探全局游戏/应用程序状态（分数、库存、设置）？ → Zustand（推荐用于R3F）带有动作/减速器的复杂状态？ → Zustand 带切片或 Redux 工具包需要状态持久化吗？ → Zustand 具有持久中间件 ### 何时使用哪个 Drei 组件需要相机控制吗？ ├─ 绕物体旋转 → OrbitControls ├─ 第一人称 → PointerLockControls ├─ 地图/自上而下 → MapControls └─ 平滑过渡 → CameraControls 需要环境照明吗？ ├─ 快速预设 → <环境预设=“日落”/> ├─ 自定义 HDR → <环境文件="/env.hdr" /> └─ 性能敏感 → <环境模糊={0.5} /> 需要文字吗？ ├─ 场景中的 3D 文本 → ├─ 2D文字广告牌 → └─ HTML 覆盖 → 需要加载吗？ ├─ GLTF 模型 → 使用GLTF ├─ 纹理 → useTexture ├─ 进度 UI → useProgress └─ 预加载 → <预加载全部/> ## 核心设置从“@react-三/纤维”导入{画布} 函数应用程序（）{ 返回（ <画布相机={{位置:[0,0,5],视场:75}} gl={{ 抗锯齿: true }} 阴影 > <环境光强度={0.5} /> <定向光位置={[10,10,5]}castShadow/> <网格> ） } ### 画布道具 <画布 camera={{ 位置, fov, 近, 远 }} // 相机配置 gl={{ 抗锯齿, alpha, powerPreference }} // WebGL 上下文 Shadows // 启用阴影贴图 dpr={[1, 2]} // 设备像素比例范围 frameloop =“需求”//“总是”| “需求”| “从不” 样式={{宽度：'100%'，高度：'100vh'}} onCreated={({ gl, scene, camera }) => {}} // 访问内部 /> ## 基本挂钩 ### useFrame - 动画循环从 '@react- Three/Fiber' 导入 { useFrame } 从 'react' 导入 { useRef } 函数 SpinningBox() { const meshRef = useRef() useFrame((状态，增量) => { // 状态: { 时钟, 相机, 场景, gl, 指针, ... } meshRef.current.rotation.y += delta meshRef.current.position.y = Math.sin(state.clock.elapsedTime) }) 返回（ <网格参考={meshRef}> <盒子几何/> <网格标准材质/> ） } ### useThree - 访问内部从'@react-三/纤维'导入{useThree} 函数 CameraLogger() { const { 相机、gl、场景、大小、视口、指针 } = useThree() // 视口: { width, height } (Three.js 单位) // 大小：{ width, height }（以像素为单位） // 指针：标准化鼠标位置（-1 到 1）返回空值 } ### useLoader - 资源加载从 '@react-two/fibre' 导入 { useLoader } 从“三”导入{TextureLoader} 从 '三个/examples/jsm/loaders/GLTFLoader' 导入 { GLTFLoader } 函数模型() { const gltf = useLoader(GLTFLoader, '/model.glb') const 纹理 = useLoader(TextureLoader, '/texture.jpg') 返回 } ## JSX 到 Three.js 的映射 // Three.js 类→camelCase JSX 元素 // 构造函数 args → args prop (数组) // 属性 → 道具 // 三. 网格 <网格位置={[0, 1, 0]} 旋转={[0, Math.PI, 0]} 比例={1.5}> {/* 三.BoxGeometry(1, 2, 1) */} {/* THREE.MeshStandardMaterial({ color: 'red' }) */} // 嵌套属性使用破折号表示法 <定向光位置={[5,5,5]} 投射阴影阴影贴图大小={[2048, 2048]} 阴影相机远={50} /> // 附加到父属性 <网格> <盒子几何/> <网格标准材质> ## Drei - 重要帮手 Drei 提供生产就绪的抽象。安装：`@react-三/drei` 导入{ 轨道控制，透视相机，环境，使用GLTF，使用纹理，文字，网页，漂浮，舞台，联系阴影，天空，星星，来自“@react-三/drei” ### 常见 Drei 组件 // 相机控制 // 环境光照（HDR） <环境预设=“日落”背景/> // 预设：公寓、城市、黎明、森林、大厅、夜晚、公园、工作室、日落、仓库 // 加载具有 draco 支持的 GLTF const { 场景、节点、材质 } = useGLTF('/model.glb') useGLTF.preload('/model.glb') // 加载纹理 const [colorMap, 法线贴图] = useTexture(['/color.jpg', '/normal.jpg']) // 3D 文本你好世界 // 3D 空间中的 HTML 叠加

点我

// 浮动动画 <浮动速度={2}rotationIntensity={0.5}floatIntensity={1}> <网格>... // 快速工作室照明 <舞台环境=“城市”强度={0.5}> <型号/> // 地面上的柔和阴影 ## 事件处理 <网格 onClick={(e) => { e.stopPropagation() console.log('点击', e.point, e.face) }} onPointerOver={(e) => setHovered(true)} onPointerOut={(e) => setHovered(false)} onPointerMove={(e) => console.log(e.point)} onPointerDown={(e) => {}} onPointerUp={(e) => {}} onDoubleClick={(e) => {}} onContextMenu={(e) => {}} > 事件对象包括：`point`、`face`、`faceIndex`、`distance`、`object`、`eventObject`、`camera`、`ray`。 ## 状态管理 ### 使用 Zustand（推荐）从“zustand”导入{创建} const useStore = 创建((set) => ({ 得分：0，游戏状态：'空闲'， addScore: (点) => set((state) => ({ 分数: state.score + 点 })), startGame: () => set({ gameState: '正在玩' }), }））函数分数显示() { const 分数 = useStore((state) => state.score) 返回{分数} } 函数游戏逻辑（）{ const addScore = useStore((state) => state.addScore) useFrame(() => { // 调用addScore的游戏逻辑 }) 返回空值 } ### 使用 React 上下文 const GameContext = createContext() 函数 GameProvider({ 孩子 }) { const [状态，调度] = useReducer(reducer, 初始状态) 返回（ {孩子} ） } // 包裹画布内容 <画布> <游戏提供者> <场景/> ## 性能模式 ### 实例化从“@react-三/drei”导入{实例，实例} 函数框({ 计数 = 1000 }) { 返回（ <实例限制={count}> <盒子几何/> <网格标准材质/> {Array.from({ 长度: 计数 }, (_, i) => ( <实例键={i} 位置={[Math.random() * 100, Math.random() * 100, Math.random() * 100]} 颜色={`hsl(${Math.random() * 360}, 50%, 50%)`} /> ))} ） } ### 选择性渲染 // 仅在需要时重新渲染 <画布frameloop =“需求”> {/* 调用invalidate()触发渲染 */} 函数控制() { const { 无效 } = useThree() 返回 invalidate()} /> } ### 记忆 // 记住昂贵的组件 const ExpenseModel = memo(function ExpenseModel({ url }) { const gltf = useGLTF(url) 返回 }) // 记住组件外部的材料/几何形状 const 几何 = new THREE.BoxGeometry(1, 1, 1) const 材质 = new THREE.MeshStandardMaterial({ color: 'red' }) 函数框() { 返回（ <网格几何={几何}材料={材料}/> ） } ### 自适应性能从 '@react-two/drei' 导入 { PerformanceMonitor, AdaptiveDpr, AdaptiveEvents } <画布> <性能监视器 onDecline={() => setQuality('low')} onIncline={() => setQuality('高')} > <自适应事件/> <场景质量={quality} /> ## 相关技能当您需要... |使用技巧 ---|--- Vanilla Three.js（无 React）| → **三人** 加载前优化资源 | → **资产管道-3d** 调试视觉/性能问题 | → **图形故障排除** ## 参考文件 * [references/drei.md]() \- 完整的 Drei 组件参考 * [references/physicals.md]() \- @react- Three/rapier 集成 * [references/postprocessing.md]() \- @react- Three/postprocessing 效果 * [references/state.md]() \- R3F 的 Zustand 模式

反应三纤维

包含技能