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