React-Three-Fiber 入门指南：在React中构建3D场景

React-Three-Fiber 入门指南：在React中构建3D场景

react-three-fiber 项目地址: https://gitcode.com/gh_mirrors/rea/react-three-fiber

什么是React-Three-Fiber？

React-Three-Fiber（简称R3F）是一个基于React的Three.js渲染器，它允许开发者使用React的声明式语法来构建3D场景。通过将Three.js的对象封装为React组件，R3F让3D开发变得更加直观和高效。

核心优势

1. 声明式编程：使用熟悉的JSX语法描述3D场景，告别命令式代码
2. React生态集成：无缝接入React的状态管理、生命周期和Hooks系统
3. 性能优异：渲染过程完全在React之外进行，无额外性能开销
4. 完整Three.js支持：支持Three.js的所有功能，无任何限制

快速开始

安装

首先需要安装核心依赖：

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

基础示例

下面是一个简单的旋转立方体示例，展示了R3F的基本用法：

import { createRoot } from 'react-dom/client'
import { Canvas, useFrame } from '@react-three/fiber'
import { useRef, useState } from 'react'

function Box(props) {
  const meshRef = useRef()
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  
  // 每帧旋转立方体
  useFrame((state, delta) => {
    meshRef.current.rotation.x += delta
  })

  return (
    <mesh
      {...props}
      ref={meshRef}
      scale={active ? 1.5 : 1}
      onClick={() => setActive(!active)}
      onPointerOver={() => setHover(true)}
      onPointerOut={() => setHover(false)}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
    </mesh>
  )
}

function Scene() {
  return (
    <Canvas>
      <ambientLight intensity={Math.PI / 2} />
      <spotLight position={[10, 10, 10]} angle={0.15} penumbra={1} />
      <Box position={[-1.2, 0, 0]} />
      <Box position={[1.2, 0, 0]} />
    </Canvas>
  )
}

createRoot(document.getElementById('root')).render(<Scene />)

关键概念解析

1. Canvas组件

<Canvas>是R3F的核心组件，它创建了一个Three.js渲染环境。所有3D对象都必须放在Canvas内部。

2. 组件化Three.js对象

R3F将Three.js的对象转换为React组件：

• <mesh> → new THREE.Mesh()
• <ambientLight> → new THREE.AmbientLight()
• 其他Three.js对象同理

3. useFrame Hook

useFrame允许组件订阅渲染循环，非常适合实现动画效果。回调函数会在每帧渲染前调用，接收state和delta参数。

4. 交互处理

R3F为3D对象提供了与DOM元素类似的交互事件：

• onClick
• onPointerOver
• onPointerOut
• 等等

进阶特性

TypeScript支持

R3F对TypeScript有很好的支持：

import type { ThreeElements } from '@react-three/fiber'

function Box(props: ThreeElements['mesh']) {
  const meshRef = useRef<THREE.Mesh>(null!)
  // ...其他代码
}

React Native支持

R3F也支持在React Native中使用：

import { Canvas } from '@react-three/fiber/native'
// ...其他代码与web版本类似

学习路径建议

1. 掌握Three.js基础：理解场景(Scene)、相机(Camera)、网格(Mesh)等核心概念
2. 熟悉React Hooks：特别是useState、useRef和自定义Hook
3. 从简单示例开始：修改上面的基础示例，尝试不同的几何体和材质
4. 逐步探索高级功能：光照、阴影、后期处理等

常见问题解答

Q: R3F会影响Three.js的性能吗？ A: 不会。R3F只是Three.js的React封装，渲染性能与原生Three.js相当。

Q: 是否支持最新的Three.js特性？ A: 完全支持。R3F会动态转换为Three.js对象，无需等待库更新。

Q: 适合大型项目吗？ A: 非常适合。React的调度能力使R3F在大型场景中表现优异。

生态系统

R3F拥有丰富的生态系统，包括：

• 实用工具库（drei）
• GLTF处理（gltfjsx）
• 后期处理（postprocessing）
• 物理引擎（rapier、cannon）
• 状态管理（zustand、jotai）
• 动画库（react-spring）

通过React-Three-Fiber，开发者可以充分利用React的组件化优势来构建复杂的3D场景，同时享受Three.js的强大功能。无论是简单的3D展示还是复杂的交互应用，R3F都能提供出色的开发体验。

react-three-fiber 项目地址: https://gitcode.com/gh_mirrors/rea/react-three-fiber