Вы можете установить three.js с помощью [link:https://www.npmjs.com/ npm] и современных инструментов сборки или быстро начните работу со статического хостинга или CDN. Для большинства пользователей установка из npm является лучшим выбором.
Что бы вы ни выбрали, будьте последовательны и импортируйте все файлы из одной и той же версии библиотеки. Смешивание файлов из разных источников может привести к включению дублирующегося кода или даже к неожиданной поломке приложения.
Все способы установки three.js зависят от модулей ES (см. [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules]), которые позволяют включать в конечный проект только те части библиотеки, которые необходимы.
Чтобы установить [link:https://www.npmjs.com/package/three three] модуль npm, откройте окно терминала в папке вашего проекта и запустите:
npm install three
Пакет будет загружен и установлен. Когда вы будете готовы импортировать его в свой код:
// Вариант 1: Импортируйте весь three.js основная библиотека.
import * as THREE from 'three';
const scene = new THREE.Scene();
// Вариант 2: Импортируйте только те детали, которые вам нужны.
import { Scene } from 'three';
const scene = new Scene();
При установке из npm вы почти всегда будете использовать какой-либо [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool], чтобы объединить все пакеты, необходимые вашему проекту, в один файл JavaScript. В то время как любой современный пакет JavaScript можно использовать с three.js , самым популярным выбором является [link:https://webpack.js.org/ webpack].
Не ко всем функциям можно получить доступ непосредственно через модуль three (также называемый "голым импортом"). Другие популярные части библиотеки, такие как элементы управления, загрузчики и эффекты постобработки, должны быть импортированы из подпапки [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm]. Чтобы узнать больше, смотрите Примеры ниже.
Узнайте больше о модулях npm по ссылке [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm](Выразительный JavaScript: Установка с помощью npm).
В three.js библиотеку можно использовать без какой-либо системы сборки, либо загрузив файлы на свой собственный веб-сервер, либо используя существующий CDN. Поскольку библиотека полагается на модули ES, любой скрипт, который ссылается на нее, должен использовать type="module", как показано ниже. Также требуется определить карту импорта, которая разрешает пустой модуль, указанный как `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-движка. Многие другие полезные компоненты, такие как элементы управления, загрузчики и эффекты постобработки, являются частью каталога [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm]. Они называются "дополнениями"(addons) (ранее назывались "примерами"(examples)), потому что, хотя вы можете использовать их в готовом виде, они также предназначены для ремиксов и кастомизации. Эти компоненты всегда синхронизируются с основной библиотекой, в то время как аналогичные пакеты сторонних разработчиков в npm поддерживаются разными пользователями и могут быть устаревшими.
Дополнения не нужно устанавливать отдельно, но их нужно импортировать отдельно. Если three.js был установлен с помощью npm, вы можете загрузить компонент [page:OrbitControls](Управление орбитой) с помощью:
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const controls = new OrbitControls( camera, renderer.domElement );
Если three.js был установлен с CDN, используйте тот же код, но с `three/addons/` в карте импорта.
<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",
"three/addons/": "https://unpkg.com/three@<version>/examples/jsm/"
}
}
</script>
<script type="module">
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const controls = new OrbitControls( camera, renderer.domElement );
</script>
Важно, чтобы все файлы использовали одну и ту же версию. Не импортируйте разные дополнения(addons) из разных версий и не используйте дополнения(addons) из версии, отличной от three.js самой библиотека.
В то время как большинство современных пакетов JavaScript теперь поддерживают модули по умолчанию, некоторые старые инструменты сборки могут этого не делать. В этих случаях вы, вероятно, можете настроить пакет для подключения модулей ES: [link:http://browserify.org/ Browserify] просто нужен плагин [link:https://github.com/babel/babelify babelify] , как пример.
Так как three.js создан для Интернета, он зависит от браузера и DOM API, которые не всегда существуют в Node.js. Некоторые из этих проблем могут быть решены с помощью прослоек, таких как [link:https://github.com/stackgl/headless-gl headless-gl], или путем замены компонентов, таких как [page:TextureLoader], пользовательскими альтернативами. Другие API-интерфейсы DOM могут быть глубоко переплетены с использующим их кодом, и обойти их будет сложнее. Мы приветствуем простые и поддерживаемые предложения `pull requests` для улучшения поддержки Node.js, но рекомендуем сначала открыть `issue`(вопрос), чтобы обсудить ваши улучшения.
Обязательно добавьте `{ "type": "module" }` в свой `package.json`, чтобы включить модули ES6 в ваш проект.