TresJS 从 v1 到最新版本迁移指南

TresJS 从 v1 到最新版本迁移指南

前言

TresJS 是一个基于 Vue 的 Three.js 封装库，它让 Three.js 的使用变得更加简单和直观。随着 TresJS 从 v1 升级到最新版本，引入了一些重要的架构变化和功能改进。本文将详细介绍这些变化，并指导开发者如何平滑迁移他们的项目。

升级步骤

首先，你需要更新你的 TresJS 核心包。根据你使用的包管理器，运行以下命令之一：

# pnpm
pnpm update @tresjs/core

# npm
npm update @tresjs/core

# yarn
yarn upgrade @tresjs/core

主要新特性

Vue 自定义渲染器架构

最新版本的 TresJS 采用了 Vue 自定义渲染器架构。这意味着：

1. 现在整个 Three.js 场景被封装在一个名为 TresCanvas 的包装组件中
2. TresCanvas 会自动创建 WebGLRenderer 和 Scene
3. 内部会创建一个新的 Vue 应用实例来渲染场景

这种架构使得 TresJS 与 Vue 的集成更加紧密，性能也更好。

TypeScript 支持和智能提示

新版本提供了全面的 TypeScript 支持：

1. 所有 Tres 组件现在都能与 Volar 完美配合
2. 构建时会基于 Three.js 的类型定义自动生成类型声明
3. 开发者可以获得完整的类型检查和智能提示

这使得开发体验大幅提升，特别是对于大型项目。

更灵活的组件导入方式

Tres 插件现在是可选的，你可以直接按需导入组件：

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
</script>

这种方式可以：

• 更好地支持 tree-shaking
• 减少最终打包体积
• 只加载实际使用的组件

重要变更点

不再需要 TresScene 组件

旧版本中需要显式使用 <TresScene> 组件，现在这个组件已被废弃。场景现在由 TresCanvas 自动创建。

迁移方法很简单：只需删除 <TresScene> 标签，将其子元素直接放在 <TresCanvas> 中。

useCatalog 已被废弃

扩展 Three.js 功能的方式发生了变化：

旧方式：

import { useCatalog } from '@tresjs/core'
const { extend } = useCatalog()
extend({ TextGeometry })

新方式：

import { extend } from '@tresjs/core'
extend({ TextGeometry })

模型引用方式简化

获取模型引用的方式更加直观：

旧方式：

watch(modelRef, ({ getModel }) => {
  const model = getModel()
  model.position.set(0, 0, 0)
})

新方式：

watch(modelRef, (model) => {
  model.position.set(0, 0, 0)
})

相机与控制器的顺序要求

现在控制器组件必须放在相机组件之后：

正确顺序：

<TresCanvas>
  <TresPerspectiveCamera />
  <TresOrbitControls />
</TresCanvas>

useTres 更名为 useTresContext

v3 版本重构了状态管理逻辑：

1. 现在使用基于 provide/inject 的上下文提供者系统
2. 不再使用大型响应式对象
3. 直接提供 scene 和 renderer 的 ref 引用

旧方式：

const { state } = useTres()
console.log(state.scene)

新方式：

const { scene } = useTresContext()
console.log(scene.value)

迁移建议

1. 建议逐步迁移，先更新依赖，然后逐个处理变更点
2. 对于大型项目，可以先在测试分支上进行迁移
3. 充分利用新的 TypeScript 支持来检查迁移后的代码
4. 注意相机和控制器的顺序问题，这是常见错误点

总结

TresJS 最新版本带来了显著的架构改进和开发体验提升。通过本指南，你应该能够顺利将项目从 v1 迁移到最新版本。新版本不仅提供了更好的性能，还大大改善了开发体验，特别是通过 TypeScript 支持和智能提示功能。