tresjs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TresJS

Vue 3 framework for building 3D scenes with Three.js. Declarative components that wrap Three.js objects.

Packages:

@tresjs/core

(required),

@tresjs/cientos

(helpers),

@tresjs/post-processing

(effects)

基于Three.js的Vue 3 3D场景构建框架，通过声明式组件封装Three.js对象。

相关包：

@tresjs/core

（必需）、

@tresjs/cientos

（辅助工具）、

@tresjs/post-processing

（特效处理）

Installation

安装

bash

undefined

bash

undefined

Core (required)

pnpm add three @tresjs/core

Helpers - controls, loaders, materials, staging

pnpm add @tresjs/cientos

Post-processing effects

pnpm add @tresjs/post-processing

undefined

pnpm add @tresjs/post-processing

undefined

Quick Reference

快速参考

Working on...	Load file
TresCanvas, useTres, useLoop	references/core.md
Controls, loaders, materials	references/cientos.md
Bloom, glitch, DOF effects	references/effects.md
Common patterns, recipes	references/cookbook.md

开发内容	参考文档
TresCanvas、useTres、useLoop	references/core.md
控制器、加载器、材质	references/cientos.md
Bloom、故障、景深特效	references/effects.md
通用模式、开发示例	references/cookbook.md

Loading Files

文件加载

Load based on your task:

references/core.md - TresCanvas setup, composables, events, primitives
references/cientos.md - OrbitControls, useGLTF, Environment, materials
references/effects.md - EffectComposer, bloom, glitch, DOF
references/cookbook.md - Load models, camera setup, animations

DO NOT load all files at once. Load only what's relevant.

根据开发任务选择参考文档：

references/core.md - TresCanvas配置、组合式函数、事件、基础组件
references/cientos.md - OrbitControls、useGLTF、Environment、材质
references/effects.md - EffectComposer、Bloom、故障、景深特效
references/cookbook.md - 模型加载、相机配置、动画

请勿一次性加载所有文件。仅加载相关内容即可。

Core Concepts

核心概念

TresCanvas

Root component that creates WebGL renderer and scene:

vue

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

<template>
  <TresCanvas shadows alpha>
    <TresPerspectiveCamera :position="[5, 5, 5]" />
    <TresMesh>
      <TresBoxGeometry />
      <TresMeshStandardMaterial color="orange" />
    </TresMesh>
    <TresAmbientLight :intensity="0.5" />
    <TresDirectionalLight :position="[3, 3, 3]" :intensity="1" />
  </TresCanvas>
</template>

用于创建WebGL渲染器和场景的根组件：

vue

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

<template>
  <TresCanvas shadows alpha>
    <TresPerspectiveCamera :position="[5, 5, 5]" />
    <TresMesh>
      <TresBoxGeometry />
      <TresMeshStandardMaterial color="orange" />
    </TresMesh>
    <TresAmbientLight :intensity="0.5" />
    <TresDirectionalLight :position="[3, 3, 3]" :intensity="1" />
  </TresCanvas>
</template>

Component Naming

组件命名

All Three.js classes available as Vue components with

Tres

prefix:

THREE.PerspectiveCamera

→

<TresPerspectiveCamera />

```
THREE.Mesh
```
→
```
<TresMesh />
```
```
THREE.BoxGeometry
```
→
```
<TresBoxGeometry />
```

THREE.MeshStandardMaterial

→

<TresMeshStandardMaterial />

Constructor arguments via

:args

prop:

vue

<TresPerspectiveCamera :args="[75, 1, 0.1, 1000]" />

所有Three.js类都可以作为带

Tres

前缀的Vue组件使用：

THREE.PerspectiveCamera

→

<TresPerspectiveCamera />

```
THREE.Mesh
```
→
```
<TresMesh />
```
```
THREE.BoxGeometry
```
→
```
<TresBoxGeometry />
```

THREE.MeshStandardMaterial

→

<TresMeshStandardMaterial />

通过

:args

属性传递构造函数参数：

vue

<TresPerspectiveCamera :args="[75, 1, 0.1, 1000]" />

Reactivity

响应式特性

Props are reactive - changes update the 3D scene:

vue

<script setup>
const color = ref('orange')
const position = ref([0, 0, 0])
</script>

<template>
  <TresMesh :position="position">
    <TresMeshStandardMaterial :color="color" />
  </TresMesh>
</template>

组件属性具备响应式 - 属性变更会同步更新3D场景：

vue

<script setup>
const color = ref('orange')
const position = ref([0, 0, 0])
</script>

<template>
  <TresMesh :position="position">
    <TresMeshStandardMaterial :color="color" />
  </TresMesh>
</template>

Primitive Component

原生组件

Inject existing Three.js objects directly:

vue

<script setup>
import { useGLTF } from '@tresjs/cientos'
const { scene } = await useGLTF('/model.glb')
</script>

<template>
  <primitive :object="scene" />
</template>

直接注入已有的Three.js对象：

vue

<script setup>
import { useGLTF } from '@tresjs/cientos'
const { scene } = await useGLTF('/model.glb')
</script>

<template>
  <primitive :object="scene" />
</template>

Available Guidance

可用指南

references/core.md - TresCanvas props, useTres, useLoop, useGraph, events, performance

references/cientos.md - OrbitControls, useGLTF, useTexture, Environment, Sky, materials, shapes

references/effects.md - EffectComposer vs EffectComposerPmndrs, bloom, glitch, DOF, effect stacking

references/cookbook.md - Load 3D model, camera with controls, animation loop, post-processing

references/core.md - TresCanvas属性、useTres、useLoop、useGraph、事件、性能优化

references/cientos.md - OrbitControls、useGLTF、useTexture、Environment、Sky、材质、图形形状

references/effects.md - EffectComposer与EffectComposerPmndrs对比、Bloom、故障、景深、特效叠加

references/cookbook.md - 3D模型加载、带控制器的相机、动画循环、后期处理