Three.js: Установка

JavaScript, Three.js

Структура проекта

Каждый проект three.js требует как минимум одного HTML-файла для определения веб-страницы и JavaScript-файла для запуска вашего кода three.js. Структура и выбор имен, приведенные ниже, не являются обязательными, но будут использоваться в этом руководстве для consistency.

  • index.html
<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<title>My first three.js app</title>
		<style>
			body { margin: 0; }
		</style>
	</head>
	<body>
		<script type="module" src="/main.js"></script>
	</body>
</html>
  • main.js
import * as THREE from 'three';

...
  • public/
    • Папка public/ иногда также называется «статической» папкой, потому что содержащиеся в ней файлы передаются на сайт без изменений. Обычно сюда помещаются текстуры, аудио и 3D-модели.

Теперь, когда мы настроили базовую структуру проекта, нам нужен способ запустить проект локально и получить к нему доступ через веб-браузер. Установка и локальная разработка могут быть выполнены с помощью npm и инструмента сборки или путем импорта three.js из CDN. Оба варианта объясняются в разделах ниже.

Вариант 1: Установка с помощью NPM и инструмента сборки

Разработка

Установка из реестра npm и использование инструмента сборки — это рекомендуемый подход для большинства пользователей. Чем больше зависимостей требует ваш проект, тем выше вероятность столкнуться с проблемами, которые статический хостинг не сможет легко решить. С инструментом сборки импорт локальных JavaScript-файлов и npm-пакетов должен работать «из коробки», без необходимости в import maps.

  1. Установите Node.js. Он понадобится для управления зависимостями и запуска инструмента сборки.
  2. Установите three.js и инструмент сборки Vite, используя терминал в папке вашего проекта. Vite будет использоваться во время разработки, но он не является частью финальной веб-страницы. Если вы предпочитаете использовать другой инструмент сборки, это нормально — мы поддерживаем современные инструменты сборки, которые могут импортировать ES-модули.
# three.js
npm install --save three

# vite
npm install --save-dev vite
  1. Из вашего терминала выполните:
npx vite

Если все прошло успешно, вы увидите URL-адрес, например http://localhost:5173, в вашем терминале, и сможете открыть этот URL, чтобы увидеть ваше веб-приложение.
Страница будет пустой — вы готовы создать сцену.

Если вы хотите узнать больше об этих инструментах перед тем, как продолжить, см.:

Продакшн

Позже, когда вы будете готовы развернуть ваше веб-приложение, вам просто нужно будет сказать Vite выполнить production-сборку — npx vite build. Все, что используется приложением, будет скомпилировано, оптимизировано и скопировано в папку dist/. Содержимое этой папки готово к размещению на вашем сайте.

Вариант 2: Импорт из CDN

Разработка

Установка без инструментов сборки потребует некоторых изменений в структуре проекта, приведенной выше.

  1. Мы импортировали код из ‘three’ (npm-пакет) в main.js, и веб-браузеры не знают, что это значит. В index.html нам нужно добавить import map, определяющий, откуда брать пакет. Поместите код ниже внутри тега <head></head>, после стилей.
<script type="importmap">
  {
    "imports": {
      "three": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.module.js",
      "three/addons/": "https://cdn.jsdelivr.net/npm/three@<version>/examples/jsm/"
    }
  }
</script>

Не забудьте заменить <version> на актуальную версию three.js, например, «v0.149.0». Самую последнюю версию можно найти на npm version list.

  1. Также нам нужно будет запустить локальный сервер для размещения этих файлов по URL-адресу, доступному для веб-браузера. Хотя технически возможно открыть HTML-файл двойным щелчком в браузере, важные функции, которые мы будем реализовывать позже, не работают при таком открытии страницы по соображениям безопасности.
    Установите Node.js, затем выполните serve, чтобы запустить локальный сервер в директории проекта:
npx serve .
  1. Если все прошло успешно, вы увидите URL-адрес, например http://localhost:3000, в вашем терминале, и сможете открыть этот URL, чтобы увидеть ваше веб-приложение.

Страница будет пустой — вы готовы создать сцену.

Доступно множество других локальных статических серверов — некоторые используют другие языки вместо Node.js, а другие являются настольными приложениями. Все они работают примерно одинаково, и мы предоставили несколько альтернатив ниже.

Продакшн

Когда вы будете готовы развернуть ваше веб-приложение, загрузите исходные файлы на ваш веб-хостинг — нет необходимости что-либо собирать или компилировать. Обратной стороной этого подхода является то, что вам нужно будет внимательно следить за обновлением import map для всех зависимостей (и зависимостей зависимостей!), которые требуются вашему приложению. Если CDN, на котором размещены ваши зависимости, временно перестанет работать, ваш сайт также перестанет работать.

ВАЖНО: Импортируйте все зависимости из одной и той же версии three.js и с одного и того же CDN. Смешивание файлов из разных источников может привести к дублированию кода или даже к неожиданным сбоям в работе приложения.

Дополнения

«Из коробки» three.js включает основы 3D-движка. Другие компоненты three.js, такие как контроллеры, загрузчики и эффекты постобработки, находятся в директории addons/. Дополнения не нужно устанавливать отдельно, но их нужно импортировать отдельно.

Пример ниже показывает, как импортировать three.js с дополнениями OrbitControls и GLTFLoader. При необходимости это также будет упомянуто в документации или примерах каждого дополнения.

import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

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

Также доступны отличные сторонние проекты для three.js.

Похожие записи

Оставьте комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

20 − четырнадцать =

Прокрутить вверх