React Three Fiber：React 生态中的 3D 渲染方案

        React Three Fiber（简称 R3F）是 Three.js 的 React 渲染器，它让你能够像写普通 React 组件一样，用声明式的 JSX 语法构建 3D 场景。与直接在 React 生命周期中手动操作 Three.js 对象的命令式写法相比，R3F 能让代码更清晰、可复用、易于维护。

一、核心概念：声明式 3D 编程

        R3F 的本质是一个自定义 React 协调器，它能够将 JSX 元素转换成 Three.js 对象。当你写 <mesh /> 时，背后实际执行的是 new THREE.Mesh()，并将 props 作为属性应用到该实例上。

与传统的 Three.js 代码对比，差异一目了然：

命令式（纯 Three.js）：

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, w/h, 0.1, 1000);
const mesh = new THREE.Mesh(geometry, material);
scene.add(mesh);
// 还需手动管理渲染循环、清理等…

声明式（R3F）：

const App = () => (
<Canvas camera={

{ position: [0, 0, 5] }}>
<ambientLight />
<mesh>
<boxGeometry />
<meshStandardMaterial color=\”orange\” />
</mesh>
</Canvas>
);

<Canvas /> 组件是 R3F 的入口，它会自动创建场景、相机、渲染器，并处理渲染循环。你只需要关注\”放什么\”和\”怎么动\”，而不是底层如何实现。

二、快速开始

1. 安装依赖：

npm install three @react-three/fiber

@react-three/fiber 依赖 three 作为对等依赖，必须一并安装。

2. 基础场景示例：

import { Canvas, useFrame } from \’@react-three/fiber\’;
import { useRef, useState } from \’react\’;

function RotatingBox() {
const meshRef = useRef();
const [hovered, setHover] = useState(false);
const [clicked, setClick] = useState(false);

// 每一帧执行：让立方体旋转
useFrame((state, delta) => {
meshRef.current.rotation.x += delta; // 使用 delta 确保动画速度与帧率解耦
});

return (
<mesh
ref={meshRef}
scale={clicked ? 1.5 : 1}
onClick={() => setClick(!clicked)}
onPointerOver={() => setHover(true)}
onPointerOut={() => setHover(false)}
>
<boxGeometry args={[1, 1, 1]} />
<meshStandardMaterial color={hovered ? \’hotpink\’ : \’orange\’} />
</mesh>
);
}

export default function App() {
return (
<Canvas>
<ambientLight intensity={0.5} />
<pointLight position={[10, 10, 10]} />
<RotatingBox />
</Canvas>
);
}

⚠️ 注意：

        使用 meshStandardMaterial 或 meshPhysicalMaterial 等基于物理的材质时，必须添加光源才能看到物体，否则物体将显示为黑色。

3. TypeScript 支持：         R3F 提供了完整的 TypeScript 类型定义。你可以通过 ThreeElements 来为自定义组件声明 props 类型：

import { ThreeElements } from \’@react-three/fiber\’;

function Box(props: ThreeElements[\’mesh\’]) {
// …
}

三、核心组件与 Hooks

1. Canvas 组件核心属性

Canvas 组件是 R3F 的根容器，支持以下常用配置属性: