Установка

Вы можете установить three.js с помощью npm и современных инструментов сборки или быстро начать работу, используя только статический хостинг или CDN. Для большинства пользователей лучшим выбором будет установка из npm.

Что бы вы ни выбрали, будьте последовательны и импортируйте все файлы из одной и той же версии библиотеки. Смешивание файлов из разных источников может привести к включению дублирующегося кода или даже к неожиданной ошибке в работе приложения.

Все способы установки three.js зависят от модулей ES, которые позволяют включать в конечный проект только те части библиотеки, которые необходимы.

Установка с помощью npm

Чтобы установить модуль npm three (ссылка), откройте окно терминала в папке вашего проекта и выполните команду:

npm install three

Пакет будет загружен и установлен. Затем вы будете готовы импортировать его в свой код:

// Option 1: Import the entire three.js core library.
import * as THREE from 'three';

const scene = new THREE.Scene();


// Option 2: Import just the parts you need.
import { Scene } from 'three';

const scene = new Scene();

При установке с помощью npm вы почти всегда будете использовать какой-либо инструмент для объединения всех пакетов, необходимых вашему проекту, в один файл JavaScript. Хотя любой современный JavaScript bundler может быть использован с three.js, наиболее популярным выбором является webpack.

Не все функции доступны непосредственно через модули three (это называется «голым импортом»). Другие популярные части библиотеки — такие как элементы управления, загрузчики и эффекты постобработки — должны быть импортированы из подпапки examples/jsm. Чтобы узнать больше, посмотрите раздел «Примеры» ниже.

Установка с использованием CDN или статического хостинга

Библиотеку three.js можно использовать без какой-либо системы сборки, загружая файлы на собственный веб-сервер или используя существующую CDN. Поскольку библиотека полагается на модули ES, любой скрипт, который ссылается на нее, должен использовать type="module", как показано ниже. Также необходимо определить Import Map (карту импорта), который разрешает голый спецификатор модуля three.

<script async src="https://unpkg.com/es-module-shims@1.3.6/dist/es-module-shims.js"></script>

<script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three@<version>/build/three.module.js"
    }
  }
</script>

<script type="module">

  import * as THREE from 'three';

  const scene = new THREE.Scene();

</script>

Поскольку карты импорта пока поддерживаются не всеми браузерами, необходимо добавить полифилл es-module-shims.js.

Примеры

Ядро three.js сосредоточено на самых важных компонентах 3D-движка. Многие другие полезные компоненты — такие как элементы управления, загрузчики и эффекты постобработки — находятся в каталоге examples/jsm.

Они называются «примерами», потому что, хотя вы можете использовать их готовыми, они также могут быть изменены и модифицированы. Эти компоненты всегда синхронизируются с основной библиотекой, в то время как аналогичные пакеты сторонних разработчиков на npm поддерживаются разными людьми и могут быть неактуальными.

Примеры не нужно устанавливать отдельно, но их нужно импортировать отдельно. Если three.js был установлен с помощью npm, вы можете загрузить компонент OrbitControls с помощью:

import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

const controls = new OrbitControls( camera, renderer.domElement );

Если three.js был установлен из CDN, используйте ту же CDN для установки других компонентов:

<script type="module">

  import { OrbitControls } from 'https://unpkg.com/three@<version>/examples/jsm/controls/OrbitControls.js';

  const controls = new OrbitControls( camera, renderer.domElement );

</script>

Важно, чтобы все файлы использовали одну и ту же версию. Не импортируйте разные примеры из разных версий и не используйте примеры из версии, отличной от версии самой библиотеки three.js.

Совместимость

Импорт CommonJS

Хотя большинство современных JavaScript-компонентов теперь поддерживают модули ES по умолчанию, некоторые старые инструменты сборки могут этого не делать. В таких случаях вы можете настроить бандлер на понимание ES-модулей: Например, для Browserify нужен только плагин babelify.

Node.js

Поскольку three.js создан для веб, он зависит от API браузера и DOM, которые не всегда существуют в Node.js. Некоторые из этих проблем могут быть решены с помощью фиксов, таких как headless-gl, или заменой таких компонентов, как TextureLoader, на собственные альтернативы. Другие DOM API могут быть глубоко переплетены с кодом, который их использует, и их будет сложнее обойти. Мы приветствуем простые и удобные для обслуживания запросы на улучшение поддержки Node.js, но рекомендуем сначала создать заявку для обсуждения ваших улучшений.

Обязательно добавьте { "type": "module" } в ваш package.json, чтобы включить модули ES6 в ваш проект node.

Была ли эта страница полезной?