TresJS 组合式 API 深度解析：构建高效 3D 场景的利器

TresJS 组合式 API 深度解析：构建高效 3D 场景的利器

前言

在现代前端开发中，Vue 3 的组合式 API（Composition API）为我们提供了更灵活、更强大的代码组织方式。TresJS 作为基于 Three.js 的 Vue 3 3D 渲染库，充分利用了这一特性，提供了一系列强大的组合式函数（composables），让开发者能够更高效地构建复杂的 3D 场景。

本文将深入解析 TresJS 中的核心组合式 API，帮助开发者掌握这些工具，从而在项目中实现更流畅的 3D 动画、交互和资源加载。

核心组合式 API 概览

TresJS 提供了一系列组合式函数，主要包括：

1. useTresContext - 获取 3D 场景上下文
2. useLoop - 控制渲染循环
3. useLoader - 加载 3D 资源
4. useTexture - 加载纹理
5. useSeek - 场景对象查找
6. useRenderLoop - 基础渲染循环控制

1. useTresContext：访问 3D 场景核心元素

useTresContext 是 TresJS 中最基础也最重要的组合式函数，它提供了对整个 3D 场景核心元素的访问能力。

基本用法

const { camera, renderer, scene } = useTresContext()

关键属性详解

| 属性 | 类型 | 描述 | |------|------|------| | camera | THREE.Camera | 当前活动相机 | | cameras | THREE.Camera[] | 场景中所有相机 | | renderer | THREE.WebGLRenderer | WebGL 渲染器实例 | | scene | THREE.Scene | 3D 场景对象 | | sizes | Object | 包含画布宽高和宽高比 | | raycaster | THREE.Raycaster | 用于指针事件的射线投射器 |

使用场景

useTresContext 特别适合在需要直接操作场景、相机或渲染器的场景中使用，例如：

• 动态切换相机
• 手动控制渲染
• 访问场景中的特定对象

2. useLoop：精细控制渲染流程

useLoop 是 TresJS v4 引入的强大工具，它提供了对渲染循环的精细控制能力。

核心功能

注册渲染回调

const { onBeforeRender } = useLoop()

onBeforeRender(({ delta }) => {
  // 在每帧渲染前执行的逻辑
  boxRef.value.rotation.y += delta
})

控制渲染流程

const { pause, resume } = useLoop()

// 暂停渲染循环
pause()

// 恢复渲染循环
resume()

回调参数详解

回调函数接收一个包含丰富信息的对象：

• delta：上一帧到当前帧的时间差（秒）
• elapsed：渲染循环开始后的总时间
• renderer：WebGL 渲染器实例
• scene：当前场景
• camera：当前活动相机

性能优化技巧

• 使用 pause 和 resume 在不需要渲染时暂停循环
• 合理使用 priority 参数优化回调执行顺序
• 在组件卸载时自动注销回调

3. useLoader：高效加载 3D 资源

useLoader 简化了 Three.js 中各种资源的加载过程。

基本用法

const { scene } = await useLoader(GLTFLoader, 'path/to/model.gltf')

组件形式使用

<template>
  <Suspense>
    <UseLoader v-slot="{ data }" :loader="GLTFLoader" url="model.gltf">
      <primitive :object="data.scene" />
    </UseLoader>
  </Suspense>
</template>

支持格式

• GLTF/GLB
• OBJ
• FBX
• 其他 Three.js 支持的格式

4. useTexture：纹理加载与管理

useTexture 提供了便捷的纹理加载方式，支持多种贴图类型。

多纹理加载

const { map, normalMap } = await useTexture({
  map: 'albedo.png',
  normalMap: 'normal.png'
})

组件形式使用

<template>
  <Suspense>
    <UseTexture v-slot="{ textures }" map="texture.png">
      <TresMeshStandardMaterial :map="textures.map" />
    </UseTexture>
  </Suspense>
</template>

支持的贴图类型

• 基础贴图 (map)
• 法线贴图 (normalMap)
• 粗糙度贴图 (roughnessMap)
• 金属度贴图 (metalnessMap)
• AO 贴图 (aoMap)
• 透明贴图 (alphaMap)
• Matcap 贴图 (matcap)

5. useSeek：场景对象查找工具

useSeek 提供了便捷的场景对象查找功能。

核心方法

const { seek, seekAll } = useSeek()

// 查找单个对象
const body = seek(model, 'name', 'car_body')

// 查找所有匹配对象
const lights = seekAll(scene, 'type', 'Light')

使用场景

• 复杂模型部件查找
• 批量修改场景对象
• 动态场景分析

6. useRenderLoop：基础渲染循环控制

useRenderLoop 提供了基础的渲染循环控制能力。

基本用法

const { onLoop } = useRenderLoop()

onLoop(({ delta }) => {
  // 每帧执行的动画逻辑
})

与 useLoop 的区别

• useRenderLoop 更轻量但不访问场景上下文
• useLoop 功能更全面，与 TresJS 深度集成

最佳实践与性能优化

1. 合理使用 Suspense：加载资源时务必使用 Suspense 组件包裹
2. 按需渲染：不需要时暂停渲染循环
3. 资源管理：及时清理不再使用的纹理和模型
4. 性能监控：利用回调进行性能分析

结语

TresJS 的组合式 API 为 Vue 开发者提供了强大而灵活的工具集，使得在 Vue 生态中构建复杂的 3D 场景变得更加简单高效。通过合理运用这些 API，开发者可以创建出性能优异、交互丰富的 3D 应用。

掌握这些组合式函数的关键在于理解它们各自的使用场景和最佳实践，希望本文能帮助你在 TresJS 项目中游刃有余地使用这些强大的工具。