vantajs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vanta.js — Animated WebGL Backgrounds Skill

Vanta.js — WebGL动画背景技能

When to use

适用场景

Decorative animated backgrounds behind hero sections
You want “wow” quickly without building a full three.js scene
Lightweight integration into static sites or React/Vue

为首页头部区域添加装饰性动画背景
希望快速实现惊艳效果，无需构建完整的three.js场景
轻量集成到静态网站或React/Vue项目中

How it works

工作原理

Vanta injects a canvas into a container element and renders an effect (many use three.js).
Typical usage: include
```
three.min.js
```
(or provide THREE) + one Vanta effect bundle.

Vanta会在容器元素中注入一个canvas并渲染特效（多数特效基于three.js实现）。
典型用法：引入
```
three.min.js
```
（或自行提供THREE对象）+ 单个Vanta特效包。

Key APIs/patterns

核心API与使用模式

Init:

const effect = VANTA.WAVES({ el: "#hero", ...options })

Update after init:
- ```
effect.setOptions({ color: 0xff88cc })
```
Resize:
- ```
effect.resize()
```
  (if container size changes)
Cleanup:
- ```
effect.destroy()
```
  (important in SPAs)

初始化：

const effect = VANTA.WAVES({ el: "#hero", ...options })

初始化后更新配置：
- ```
effect.setOptions({ color: 0xff88cc })
```
自适应调整：
- ```
effect.resize()
```
  （当容器尺寸变化时调用）
资源清理：
- ```
effect.destroy()
```
  （在单页应用中至关重要）

Common pitfalls

常见问题

Container has no size → nothing visible
- Ensure the target element has explicit width/height (or is laid out).
Multiple WebGL canvases on one page → GPU load
- Keep to 1–2 effects/page.
Mobile/older GPU issues
- Provide a fallback background color/image; consider disabling on small screens.
Bundling in frameworks
- Some builds require
```
window.THREE
```
  or passing
```
THREE
```
  in options.

容器无尺寸 → 无法显示特效
- 确保目标元素设置了明确的宽高（或已正确布局）。
单页中存在多个WebGL画布 → 增加GPU负载
- 每页建议只使用1-2个特效。
移动端/旧GPU兼容性问题
- 提供备用背景色或图片；考虑在小屏幕上禁用特效。
框架打包问题
- 部分构建环境需要全局的
```
window.THREE
```
  对象，或在配置中传入THREE。

Quick recipes

快速实现示例

1) Minimal waves background

1) 极简波浪背景

html

<div id="hero" style="height: 70vh;"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r134/three.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/vanta/dist/vanta.waves.min.js"></script>
<script>
  const effect = VANTA.WAVES({ el: "#hero", color: 0x0b1220, shininess: 40, waveHeight: 16, zoom: 0.9 });
</script>

html

<div id="hero" style="height: 70vh;"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r134/three.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/vanta/dist/vanta.waves.min.js"></script>
<script>
  const effect = VANTA.WAVES({ el: "#hero", color: 0x0b1220, shininess: 40, waveHeight: 16, zoom: 0.9 });
</script>

2) React cleanup pattern (concept)

2) React中的资源清理模式（概念）

Create effect in
```
useEffect
```
, store in ref, call
```
destroy()
```
on unmount.

在
```
useEffect
```
中创建特效，存储在ref中，卸载组件时调用
```
destroy()
```
。

What to ask the user

需向用户确认的信息

Which effect (waves, birds, fog, net, etc.) and brand colors?
Must it run on mobile? If yes, what’s acceptable FPS/quality?
Is it behind text (needs contrast/readability)?

选择哪种特效（波浪、飞鸟、雾气、网格等）以及品牌配色？
是否需要在移动端运行？如果是，可接受的帧率/画质是多少？
特效是否在文本后方（需要保证对比度与可读性）？