# React 三纤维基础知识通过 React 组件声明式 Three.js。 R3F 通过自动处置、反应式更新和 React 生命周期集成将 Three.js 对象映射到 JSX 元素。 ## 快速入门从'@react-三/纤维'导入{画布}；函数应用程序（）{ 返回（ <画布> <环境光强度={0.5} /> <网格> ）； } ## 核心原理：声明式场景图 R3F 将 Three.js 命令式 API 转换为 React 的声明式模型： Three.js（势在必行）| R3F（声明式） ---|--- `new THREE.Mesh()` | `<网格>` `mesh.position.set(1, 2, 3)` | `<网格位置={[1, 2, 3]}>` `场景.添加（网格）` | JSX 嵌套句柄层次结构 `mesh.geometry.dispose()` |自动卸载 ## 画布配置从'@react-三/纤维'导入{画布}； <画布 // 渲染器设置 gl={{ 抗锯齿: true, alpha: false, powerPreference: '高性能' }} dpr={[1, 2]} // 设备像素比例范围 Shadows // 启用阴影贴图 // 相机（默认：PerspectiveCamera）相机={{ 视场角：75，接近：0.1，远：1000，位置：[0,0,5] }} // 或者使用拼字法正字法相机={{变焦：50，位置：[0,0,100]}} // 性能 frameloop="demand" // '总是' | '需求' | ‘从不’ Performance={{ min: 0.5 }} // 自适应性能 // 事件 onCreated={({ gl, 场景, 相机 }) => { // 挂载后访问Three.js对象 }} // 尺寸调整样式={{宽度：'100vw'，高度：'100vh'}} /> ### 帧循环模式模式|何时使用 ---|--- `总是` |连续动画（游戏、模拟） `需求` |静态场景，仅在状态变化时重新渲染 `从来没有` |通过“invalidate()”手动控制 // 手动失效的需求模式从'@react-三/纤维'导入{useThree}；函数控制() { const invalidate = useThree(state => state.invalidate); 常量handleDrag = () => { // 更新状态... 无效（）； // 请求重新渲染 }; } ## 场景层次结构 JSX 嵌套 = Three.js 父子关系： <组位置={[0, 2, 0]} 旋转={[0, Math.PI / 4, 0]}> {/* 子级继承父级变换 */} <网格位置={[1,0,0]}> <网格位置={[-1, 0, 0]}> ### 常用容器组件 // 组：变换容器（无渲染） <组位置={[0, 0, 0]} /> // Object3D：基类，很少直接使用 // 场景：通常是隐式的（Canvas 创建一个） <场景/> ## 相机系统 ### 默认透视相机 <画布相机={{ fov: 75, // 视野（度） spect: 宽度/高度, // 自动计算 close: 0.1, // 近裁剪平面 far: 1000, // 远剪裁平面位置：[0,5,10] }} /> ### 自定义相机组件从 '@react- Three/drei' 导入 { PerspectiveCamera } ；函数场景（）{ 返回（ <> <透视相机 makeDefault // 设置为活动相机视野={60} 位置={[0,2,8]} /> {/* 场景内容 */} ）； } ### 相机访问从'@react-三/纤维'导入{useThree}；函数CameraController() { const { 相机 } = useThree(); 使用效果（（）=> { 相机.lookAt(0, 0, 0); }, [相机]); 返回空值； } ## 照明 ### 灯光类型 // 环境：均匀，无方向 // 方向性：类似太阳的平行光线 <定向光位置={[5,10,5]} 强度={1} 投射阴影 /> // Point: 从位置辐射 <点光源位置={[0, 5, 0]} 强度={1} distance={20} // 范围（0 = 无限） Decay={2} // 物理衰减 /> // 光斑：锥形 <聚光灯位置={[0, 10, 0]} angle={Math.PI / 6} // 圆锥角 penumbra={0.5} // 边缘柔软度投射阴影 /> // 半球：天空/地面渐变 <半球光天空颜色=“#87ceeb” 地面颜色=“#362907” 强度={0.6} /> ### 阴影设置 <画布阴影> <定向光投射阴影位置={[10,10,10]} 阴影贴图大小={[2048, 2048]} 阴影相机远={50} 阴影相机左={-10} 阴影相机右={10} 阴影相机顶部={10} 阴影相机底部={-10} /> <网格投射阴影> <盒子几何/> <网格标准材质/> <网格接收阴影旋转={[-Math.PI / 2, 0, 0]} 位置={[0, -1, 0]}> <网格标准材质/> ## 渲染循环（useFrame） `useFrame` 每帧运行（目标为 60fps）。这就是动画发生的地方。从'@react-三/纤维'导入{useFrame，useThree}；从'react'导入{useRef}；函数旋转框（）{ const meshRef = useRef(null!); useFrame((状态，增量) => { // state：R3F状态（相机、场景、时钟等） // delta：自上一帧以来的时间（秒） meshRef.current.rotation.x += delta; meshRef.current.rotation.y += delta * 0.5; }); 返回（ <网格参考={meshRef}> <盒子几何/> <网格法线材质/> ）； } ### useFrame 状态对象 useFrame((状态) => { state.clock // 三.时钟 state.clock.elapsedTime // 总时间（秒） state.camera // 活动相机 state.scene // 场景对象 state.gl // WebGL渲染器 state.size // { 宽度, 高度 } state.viewport // { 宽度、高度、因子、距离 } state.mouse // 标准化鼠标位置 [-1, 1] state.raycaster // 三.Raycaster }); ### 渲染优先级 // 优先级低的先运行，优先级高的后运行 // 默认为 0 useFrame(() => { // 更新物理 }, -1); // 在默认之前运行 useFrame(() => { // 更新视觉效果 }, 0); // 默认 useFrame(() => { // 后处理/相机 }, 1); // 默认后运行 ## 访问 Three.js 对象 ### 使用三钩从'@react-三/纤维'导入{useThree}；函数场景信息（）{ 常量{ gl, // WebGL渲染器 scene, // 三.场景相机, // 活动相机 size, // 画布尺寸 viewport, // 以 Three.js 为单位的视口时钟, // 三.时钟 set, // 更新状态 get, // 获取当前状态 invalidate, // 请求重新渲染（需求模式） advance, // 前进一帧（从不模式） } = useThree(); 返回空值； } ### 直接访问参考从'react'导入{useRef}；从 '三' 导入 * 作为三；函数 DirectAccess() { const meshRef = useRef(null!); const MaterialRef = useRef(null!); 使用效果（（）=> { // 直接访问 Three.js API meshRef.current.geometry.computeBoundingBox(); MaterialRef.current.needsUpdate = true; }, []); 返回（ <网格参考={meshRef}> <盒子几何/> ）； } ## 活动 R3F 提供网格上的指针事件： <网格 onClick={(e) => console.log('click', e.point)} onContextMenu={(e) => console.log('右键单击')} onDoubleClick={(e) => console.log('双击')} onPointerOver={(e) => console.log('悬停')} onPointerOut={(e) => console.log('unhover')} onPointerDown={(e) => console.log('down')} onPointerUp={(e) => console.log('up')} onPointerMove={(e) => console.log('移动')} > <盒子几何/> <网格标准材质/> ### 事件对象 onClick={(e) => { e.stopPropagation(); // 停止事件冒泡 e.point // THREE.Vector3交点 e.distance // 距相机的距离 e.object // 相交对象 e.face // 相交面 e.faceIndex // 人脸索引 e.uv // UV坐标 e.camera // 用于光线投射的相机 e.delta // 距上次事件的距离 }} ## 悬念与加载 R3F 与 React Suspense 集成以实现异步加载：从'react'导入{Suspense}；从'@react-三/纤维'导入{useLoader}；从 '三个/examples/jsm/loaders/GLTFLoader' 导入 { GLTFLoader }；函数模型() { const gltf = useLoader(GLTFLoader, '/model.glb'); 返回 ; } 函数应用程序（）{ 返回（ <画布> }> <型号/> ）； } 函数 LoadingSpinner() { const meshRef = useRef(null!); useFrame((_, delta) => { meshRef.current.rotation.z += delta * 2; }); 返回（ <网格参考={meshRef}> ）； } ## 依赖关系 { “依赖项”：{ “@react-三/纤维”：“^8.15.0”， “三”：“^0.160.0”， “反应”：“^18.2.0”， “反应-dom”：“^18.2.0” }, “开发依赖项”：{ “@types/三”：“^0.160.0” } } ## 文件结构 r3f-基础知识/ ├── 技能.md ├── 参考资料/ │ ├── canvas-props.md # 完整的 Canvas 道具参考 │ ├── hooks-api.md # useThree, useFrame, useLoader │ └── event-system.md # 事件处理深入探讨 └── 脚本/ ├── 模板/ │ ├── basic-scene.tsx # 最小启动器 │ ├── lit-scene.tsx # 适当的照明 │ └── Interactive.tsx # 带事件和动画 └── 实用程序/ └── canvas-config.ts # 预设配置 ## 参考 * `references/canvas-props.md` — 完整的 Canvas 配置选项 * `references/hooks-api.md` — 所有 R3F 钩子及示例 * `references/event-system.md` — 指针事件和光线投射

R3f 基础知识

包含技能