TvT.js 技术文档：基于ThreeJS与Vue3的3D可视化开发框架

2026-02-04 04:04:13作者：薛曦旖Francesca

1. 安装指南

环境要求

Node.js 16.x 或更高版本
Yarn 1.x 或 npm 7.x
现代浏览器（推荐Chrome/Firefox最新版）

安装步骤

# 克隆仓库
git clone https://github.com/hawk86104/three-vue-tres.git

# 进入项目目录
cd three-vue-tres

# 安装依赖（推荐使用yarn）
yarn

# 或使用npm
npm install

2. 项目使用说明

开发模式

# 启动开发服务器
yarn dev

# 同时启动开发服务器和预览
yarn both

构建项目

# 生产环境构建
yarn build

# 预览生产构建
yarn pre.build

运行特定示例

# 开发模式运行单个示例
yarn pre.dev.one [示例名称]

# 构建单个示例
yarn pre.build.one [示例名称]

3. 项目API使用文档

核心组件

<!-- 基础3D场景结构 -->
<TresCanvas window-size>
  <TresPerspectiveCamera />
  <TresMesh>
    <TresTorusGeometry :args="[1, 0.5, 16, 32]" />
    <TresMeshBasicMaterial color="orange" />
  </TresMesh>
</TresCanvas>

常用API

// 纹理加载
const pTexture = await useTexture(['./texture.jpg'])

// 渲染循环
const { onLoop } = useRenderLoop()
onLoop(({ delta }) => {
  // 每帧执行的逻辑
})

// 响应式状态管理
const position = reactive({ x: 0, y: 0, z: 0 })

组件列表

组件名	说明
`<TresCanvas>`	3D画布容器
`<TresMesh>`	3D物体基类
`<TresGeometry>`	几何体组件
`<TresMaterial>`	材质组件
`<TresLight>`	光源组件
`<TresCamera>`	相机组件

4. 项目安装方式

CDN引入（简易版）

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
  <script src="https://unpkg.com/tresjs@latest"></script>
</head>
<body>
  <div id="app"></div>
  <script>
    const { createApp } = Vue
    const { TresCanvas } = TresJS
    
    createApp({
      template: `
        <TresCanvas>
          <!-- 3D内容 -->
        </TresCanvas>
      `
    }).mount('#app')
  </script>
</body>
</html>

模块化安装（推荐）

# 在新项目中安装核心依赖
yarn add three @tresjs/core

项目结构说明

three-vue-tres/
├── public/            # 静态资源
├── src/               # 主项目源码
│   ├── assets/        # 静态资源
│   ├── components/    # 公共组件
│   ├── plugins/       # 插件系统
│   └── utils/         # 工具函数
├── examples/          # 示例项目
└── docs/              # 文档系统