Introduction 介绍

React-three-fiber是threejs的React渲染器

用声明式的语法,配合可复用、自包含的组件来创建可以根据状态响应的可轻松交互的三维场景,并且可以轻松融入React的生态系统。

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

有任何限制么?

比纯Threejs慢么?

会跟得上最新的Threejs的功能么

任何在Threejs中可以用的,在react-three-fiber中都可以用,没有任何例外。

不会。它没有其他额外开销。组件的渲染是在React之外的。基于React的调度能力,它在某些方面的性能还优于直接使用Threejs。

是的。它通过JSX语法来实现Threejs的各种组件,<mesh /> 会被动态的转换成new THREE.Mesh().如果一个Threejs版本添加、删除或者改变了一些能力,你的项目的代码自然就会用上相关的能力,并不会需要进行额外的升级操作。

What does it look like?

让我们创建一个可复用的组件,它拥有自己的状态会根据用户的行为产生变化

效果 demo

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

function Box(props) {
  // This reference will give us direct access to the mesh
  const meshRef = useRef()
  // Set up state for the hovered and active state
  const [hovered, setHover] = useState(false)
  const [active, setActive] = useState(false)
  // Subscribe this component to the render-loop, rotate the mesh every frame
  useFrame((state, delta) => (meshRef.current.rotation.x += delta))
  // Return view, these are regular three.js elements expressed in JSX
  return (
    <mesh
      {...props}
      ref={meshRef}
      scale={active ? 1.5 : 1}
      onClick={(event) => setActive(!active)}
      onPointerOver={(event) => setHover(true)}
      onPointerOut={(event) => setHover(false)}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
    </mesh>
  )
}

createRoot(document.getElementById('root')).render(
  <Canvas>
    <ambientLight />
    <pointLight position={[10, 10, 10]} />
    <Box position={[-1.2, 0, 0]} />
    <Box position={[1.2, 0, 0]} />
  </Canvas>,

TypeScript 代码效果 和 React Native 代码效果可查看英文官网

First steps

在开始之前,您需要熟悉 React 和 Three.js。如果您对 React 不确定,请查阅官方 React 文档,特别是关于 hooks 的部分。至于 Three.js,请确保您至少浏览以下链接:

确保您对 Three.js 有基本的了解。最好把这个网站一直开着。

当您了解场景scene、相机camera、网格mesh、几何geometry、材质material是什么时,请fork这个演示案例

查找你看到的 JSX 元素(如mesh、ambientLight等),所有 Three.js 的导出都是针对 three-fiber 的 native exports,这里就是可以理解为所有 threejs 类型都能在 R3F 中用 JSX
方式使用。

尝试更改一些值,滚动我们的 API 以查看各种设置和 hooks 的作用。

一些有用的材料:

Three.js 文档示例

Discover Three.js,特别是最佳实践的技巧章节

Bruno Simons 的 Three.js 之旅,不错的英文视频付费教程,现在包括一个完整的 R3F 章节。

我的 Threejs 与图形学课程 — 正在筹备中。

Eco system

three-fiber 周围有一个充满活力和广泛的生态系统,充满了库、工具和模块。


@react-three/drei - 有用的库,这本身就是一个生态系统

@react-three/gltfjsx - 将 GLTF 转换为 JSX 组件

@react-three/postprocessing - 后处理效果

@react-three/test-renderer - 用于在节点中进行单元测试

@react-three/flex - 适用于 react-three-fiber 的 flexbox

@react-three/xr - VR/AR 控制器和事件

@react-three/csg - 构造实体几何

@react-three/rapier - 使用 Rapier 进行 3D 物理学

@react-three/cannon - 使用 Cannon 进行 3D 物理学

@react-three/p2 - 使用 P2 进行 2D 物理学

@react-three/a11y - 真正的 a11y 场景

@react-three/gpu-pathtracer - 逼真的路径跟踪

create-r3f-app next - nextjs 起始器

lamina - 基于层的着色器材料

zustand - 基于 flux 的状态管理

jotai - 基于 atoms 的状态管理

valtio - 基于代理的状态管理

react-spring - 基于弹簧物理的动画库

framer-motion-3d - framer motion,一个流行的动画库

use-gesture - 鼠标/触摸手势

leva - 在几秒钟内创建 GUI 控件

maath - 数学助手的工具箱

miniplex - ECS(实体管理系统)

composer-suite - 组合着色器、粒子、效果和游戏机制