Установка и подключение библиотеки

Подключение через CDN

Наиболее быстрый способ начать работу с библиотекой — использовать CDN (Content Delivery Network). Для этого достаточно добавить тег <script> в HTML-документ:

<script src="https://cdn.jsdelivr.net/npm/three@0.161.0/build/three.min.js"></script>

Особенности подключения через CDN:

  • Быстрая интеграция — не требуется установка дополнительных пакетов.
  • Всегда последняя стабильная версия при указании без конкретного номера версии.
  • Подходит для прототипирования и небольших проектов.

При использовании CDN необходимо учитывать, что все модули библиотеки будут загружены глобально, что может увеличить время загрузки страницы, если проект масштабный.

Установка через npm

Для проектов на Node.js и сборщиков модулей (Webpack, Vite, Parcel) рекомендуется установка через npm:

npm install three

После установки библиотека доступна в проекте через import:

import * as THREE from 'three';

Преимущества npm-подхода:

  • Позволяет подключать только нужные модули, что снижает размер сборки.
  • Обеспечивает совместимость с современными сборщиками и системами модулей.
  • Удобно использовать TypeScript благодаря встроенным типам (@types/three не требуется).

Основные модули Three.js

Three.js построен модульно. Даже при глобальном подключении через CDN существуют ключевые пространства имен:

  • THREE.Scene — создаёт сцену для размещения объектов.
  • THREE.PerspectiveCamera и THREE.OrthographicCamera — камеры для визуализации.
  • THREE.WebGLRenderer — рендеринг сцены с использованием WebGL.
  • THREE.Mesh, THREE.Geometry, THREE.Material — основные компоненты объектов 3D.
  • THREE.TextureLoader, THREE.ObjectLoader, THREE.GLTFLoader — загрузка текстур и моделей.

Модульная структура npm позволяет импортировать только необходимые классы:

import { Scene, PerspectiveCamera, WebGLRenderer, Mesh, BoxGeometry, MeshBasicMaterial } from 'three';

Это снижает размер итогового бандла и ускоряет загрузку проекта.

Подключение вспомогательных модулей

Three.js включает отдельные дополнения и расширения, например:

  • OrbitControls — управление камерой мышью.
  • GLTFLoader — загрузка 3D-моделей в формате glTF.
  • RGBELoader — работа с HDR-текстурами.
  • EffectComposer — постобработка сцены.

При установке через npm их подключение выглядит так:

import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';

Для подключения через CDN необходимо использовать отдельные скрипты с корректными путями к examples/jsm или examples/js.

Интеграция с HTML и Canvas

Three.js рендерит сцену на элемент <canvas>, который можно встроить напрямую:

<canvas id="three-canvas"></canvas>

Или создать программно в Jav * aScript:

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

Ключевые параметры WebGLRenderer:

  • antialias — сглаживание границ объектов.
  • alpha — прозрачность фона.
  • precision — точность рендеринга (highp, mediump).

Совместимость с сборщиками

При использовании сборщиков важно правильно настроить импорты и пути. Для модульной структуры через npm:

  • Использовать import вместо глобального THREE.
  • Подключать примеры и загрузчики из three/examples/jsm.
  • Настраивать обработку ES6-модулей в сборщике (Babel, TypeScript).

Настройка версии библиотеки

Three.js активно развивается, поэтому важно фиксировать версию при установке:

npm install three@0.161.0

Это предотвращает неожиданное изменение API и обеспечивает стабильность кода при обновлениях.

Проверка подключения

После установки и подключения можно проверить работу библиотеки простым скриптом:

console.log(THREE.REVISION); // выводит версию Three.js

Если в консоли отображается номер версии, библиотека подключена корректно. Это базовая проверка перед началом работы с рендерингом сцены и объектами.

Оглавление