|
|
@@ -9,152 +9,256 @@
|
|
|
<body>
|
|
|
<h1>安装（[name]）</h1>
|
|
|
|
|
|
- <p>
|
|
|
- 你可以使用[link:https://www.npmjs.com/ npm]以及现代构建工具来安装 three.js ，也可以只需静态主机或是 CDN 来快速上手。对于大多数用户来说，从 npm 安装是最佳选择。
|
|
|
- </p>
|
|
|
+ <h2>项目结构</h2>
|
|
|
|
|
|
<p>
|
|
|
- 无论你选择哪种方式，请始终保持一致，并注意从相同版本的库中导入所有文件。混合不同来源的文件可能会导致包含重复代码，甚至会以意料之外的方式破坏应用程序，
|
|
|
+ 每个 three.js 项目至少需要一个 HTML 文件来定义网页，以及一个 JavaScript 文件来运行你的 three.js 代码。下面的结构和命名选择并非必需，但为了保持一致性，本指南将在全文中使用。
|
|
|
</p>
|
|
|
|
|
|
+ <ul>
|
|
|
+ <li>
|
|
|
+ <i>index.html</i>
|
|
|
+ <code>
|
|
|
+ <!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>
|
|
|
+ </code>
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ <i>main.js</i>
|
|
|
+ <code>
|
|
|
+import * as THREE from 'three';
|
|
|
+
|
|
|
+...
|
|
|
+ </code>
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ <i>public/</i>
|
|
|
+ <ul>
|
|
|
+ <li>
|
|
|
+ <i>public/</i> 文件夹有时也被称为 "静态（static）"文件夹，因为其中包含的文件会原封不动地推送到网站上。纹理（textures）、音频和 3D 模型通常会放在这里。
|
|
|
+ </li>
|
|
|
+ </ul>
|
|
|
+ </li>
|
|
|
+ </ul>
|
|
|
+
|
|
|
<p>
|
|
|
- 所有安装 three.js 的方式都依赖于 ES modules（参见 [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules]）。ES modules使你能够在最终项目中包含所需库的一小部分。
|
|
|
+ 现在我们已经建立了基本的项目结构，便需要一种方法在本地运行并通过浏览器访问它。我们可以使用 npm 和构建工具来完成安装和本地开发，也可以从 CDN 导入 three.js。下面将对这两种方案进行说明。
|
|
|
</p>
|
|
|
|
|
|
- <h2>安装自 npm</h2>
|
|
|
+ <h2>方案 1：使用 NPM 和构建工具进行安装</h2>
|
|
|
+
|
|
|
+ <h3>开发</h3>
|
|
|
|
|
|
<p>
|
|
|
- 要安装[link:https://www.npmjs.com/package/three three] 的 npm 模块，请在你的项目文件夹里打开终端窗口，并运行：
|
|
|
+ 对于大多数用户而已，从 [link:https://www.npmjs.com/ npm 包注册表中心] 安装并使用 [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC 构建工具] 会是一个更推荐的方案。因为项目需要的依赖越多，就越有可能遇到静态托管无法轻易解决的问题。而使用构建工具，导入本地 JavaScript 文件和 npm 软件包将会是开箱即用的，无需导入映射（import maps）。
|
|
|
</p>
|
|
|
|
|
|
- <code>
|
|
|
- npm install three
|
|
|
- </code>
|
|
|
+ <ol>
|
|
|
+ <li>
|
|
|
+ 安装 [link:https://nodejs.org/ Node.js]。我们需要它来管理依赖项和运行构建工具。
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ <p>
|
|
|
+ 在项目文件夹中通过 [link:https://www.joshwcomeau.com/javascript/terminal-for-js-devs/ 终端] 安装 three.js 和构建工具 [link:https://vitejs.dev/ Vite]。Vite 将在开发过程中使用，但不会被打包成为最终网页的一部分。当然，除了 Vite 你也可以使用其他支持导入 [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC ES Modules] 的现代构建工具。
|
|
|
+ </p>
|
|
|
+ <code>
|
|
|
+# three.js
|
|
|
+npm install --save three
|
|
|
+
|
|
|
+# vite
|
|
|
+npm install --save-dev vite
|
|
|
+ </code>
|
|
|
+ <aside>
|
|
|
+ <details>
|
|
|
+ <summary>安装时我的项目中新增了 <i>node_modules/</i> 和 <i>package.json</i>。它们是什么？</summary>
|
|
|
+ <p>
|
|
|
+ npm 使用 <i>package.json</i> 来描述你已经安装的每个依赖项的版本。如果有其他人和你一起开发项目，他们只需运行 <i>npm install</i> 就能安装每个依赖项的原始版本。如果你在使用版本控制器（如：Git、SVN）来控制代码版本，那么 <i>package.json</i> 应当被提交。
|
|
|
+ </p>
|
|
|
+ <p>
|
|
|
+ npm 将每个依赖项的代码放在 <i>node_modules/</i> 下的文件夹中。当Vite构建应用程序时，它会看到 “three” 的导入，并自动从该文件夹中提取 three.js 文件。 <i>node_modules/</i> 文件夹仅在开发过程中使用，不应上传到你的网络托管提供商或提交到版本历史记录中。
|
|
|
+ </p>
|
|
|
+ </details>
|
|
|
+ </aside>
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ 在终端运行：
|
|
|
+ <code>
|
|
|
+ npx vite
|
|
|
+ </code>
|
|
|
+ <aside>
|
|
|
+ <details>
|
|
|
+ <summary><i>npx</i> 是什么？</summary>
|
|
|
+ <p>
|
|
|
+ npx 与 Node.js 一同安装，可运行 Vite 等命令行程序，这样你就不必自己在 <i>node_modules/</i> 中搜索正确的文件。如果你愿意，可以将 [link:https://vitejs.dev/guide/#command-line-interface Vite 的常用命令] 放入 [link:https://docs.npmjs.com/cli/v9/using-npm/scripts package.json:scripts] 列表，然后使用 <i>npm run dev</i> 代替。
|
|
|
+ </p>
|
|
|
+ </details>
|
|
|
+ </aside>
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ 如果一切顺利，你会在终端中看到一个类似 <i>http://localhost:5173</i> 的 URL，打开该 URL 就能看到你的网络应用程序。
|
|
|
+ </li>
|
|
|
+ </ol>
|
|
|
|
|
|
<p>
|
|
|
- 包将会被下载并安装。然后你就可以将它导入你的代码了：
|
|
|
+ 目前页面将会是空白的，不过你已经准备好可以开始[link:#manual/zh/introduction/Creating-a-scene 创建一个场景]了。
|
|
|
</p>
|
|
|
|
|
|
- <code>
|
|
|
- // 方式 1: 导入整个 three.js核心库
|
|
|
- import * as THREE from 'three';
|
|
|
-
|
|
|
- const scene = new THREE.Scene();
|
|
|
-
|
|
|
+ <p>
|
|
|
+ 如果你想在继续之前进一步了解这些工具，请参阅：
|
|
|
+ </p>
|
|
|
|
|
|
- // 方式 2: 仅导入你所需要的部分
|
|
|
- import { Scene } from 'three';
|
|
|
+ <ul>
|
|
|
+ <li>
|
|
|
+ [link:https://threejs-journey.com/lessons/local-server three.js journey: Local Server]
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ [link:https://vitejs.dev/guide/cli.html Vite: Command Line Interface]
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ [link:https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Package_management MDN: Package management basics]
|
|
|
+ </li>
|
|
|
+ </ul>
|
|
|
|
|
|
- const scene = new Scene();
|
|
|
- </code>
|
|
|
+ <h3>生产</h3>
|
|
|
|
|
|
<p>
|
|
|
- 从npm上进行安装的时候，几乎总是使用某种构建工具（[link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool]）来将你项目中需要的所有包组合到一个独立的JavaScript软件中。虽然任何现代的 JavaScript 打包器都可以和 three.js 一起使用，但最流行的选择是 [link:https://webpack.js.org/ webpack] 。
|
|
|
+ 之后，当你准备部署网络应用程序时，只需要让 Vite 运行生产构建 - <i>npx vite build</i>。应用程序使用的所有内容都将被编译、优化并复制到 <i>dist/</i> 文件夹中。该文件夹中的内容就可以托管到你的网站上了。
|
|
|
</p>
|
|
|
|
|
|
+ <h2>方案 2：从 CDN 导入</h2>
|
|
|
+
|
|
|
+ <h3>开发</h3>
|
|
|
+
|
|
|
+ <p>在不使用构建工具的情况下进行安装，需要对上述项目结构进行一些修改。</p>
|
|
|
+
|
|
|
+ <ol>
|
|
|
+ <li>
|
|
|
+ <p>
|
|
|
+ 我们在 <i>main.js</i> 中从 "three"（一个 npm 软件包）导入了代码，但网络浏览器并不知道这意味着什么。在 <i>index.html</i> 中，我们需要添加一个[link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap 导入映射]（import map）来定义从哪里获取软件包。将下面的代码放在 <i><head></head></i> 标签内、样式（styles）之后。
|
|
|
+ </p>
|
|
|
+ <code>
|
|
|
+<script type="importmap">
|
|
|
+ {
|
|
|
+ "imports": {
|
|
|
+ "three": "https://unpkg.com/three@<version>/build/three.module.js",
|
|
|
+ "three/addons/": "https://unpkg.com/three@<version>/examples/jsm/"
|
|
|
+ }
|
|
|
+ }
|
|
|
+</script>
|
|
|
+ </code>
|
|
|
+ <p>
|
|
|
+ 不要忘记将上述链接中的 <i><version></i> 替换为 three.js 的实际版本，如 <i>"v0.149.0"</i>。最新版本可在 [link:https://www.npmjs.com/package/three?activeTab=versions npm 版本列表]中找到。
|
|
|
+ </p>
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ <p>
|
|
|
+ 我们还需要运行一个<i>本地服务器</i>，将这些文件托管到网络浏览器可以访问的 URL 上。虽然从技术上讲，双击 HTML 文件并在浏览器中打开它是可行的，但出于安全原因，这样打开的页面无法使用我们稍后要使用的重要功能。
|
|
|
+ </p>
|
|
|
+ <p>
|
|
|
+ 安装 [link:https://nodejs.org/ Node.js]，然后运行 [link:https://www.npmjs.com/package/serve serve] 在项目目录中启动本地服务器：
|
|
|
+ </p>
|
|
|
+ <code>
|
|
|
+ npx serve .
|
|
|
+ </code>
|
|
|
+ </li>
|
|
|
+ <li>
|
|
|
+ 如果一切顺利，你会在终端中看到一个类似 http://localhost:3000 的 URL，打开该 URL 就能看到你的网络应用程序。
|
|
|
+ </li>
|
|
|
+ </ol>
|
|
|
+
|
|
|
<p>
|
|
|
- 并非所有功能都可以通过 <em>three</em> 模块来直接访问（也称为“裸导入”）。three.js 中其它较为流行的部分 —— 如控制器（control）、加载器（loader）以及后期处理效果（post-processing effect） —— 必须从 [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] 子目录下导入。了解更多信息，请参阅下方的<em>示例</em>。
|
|
|
+ 目前页面将会是空白的，不过你已经准备好可以开始[link:#manual/zh/introduction/Creating-a-scene 创建一个场景]了。
|
|
|
</p>
|
|
|
|
|
|
<p>
|
|
|
- 你可以从 [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm] 来了解更多有关 npm 模块的信息。
|
|
|
+ 还有许多其他本地静态服务器可供选择——有些使用不同的语言而不是 Node.js，有些则是桌面应用程序。它们的工作方式基本相同，下文中则提供了一些替代方案。
|
|
|
</p>
|
|
|
|
|
|
- <h2>从CDN或静态主机安装</h2>
|
|
|
+ <details>
|
|
|
+ <summary>更多本地服务器</summary>
|
|
|
|
|
|
- <p>
|
|
|
- 通过将文件上传到你自己的服务器，或是使用一个已存在的CDN，three.js 便可以不借助任何构建系统来进行使用。由于 three.js 依赖于ES module，因此任何引用它的script标签必须使用<em>type="module"</em>。如下所示：
|
|
|
- </p>
|
|
|
+ <h3>命令行（Command Line）</h3>
|
|
|
|
|
|
- <code>
|
|
|
- <script type="importmap">
|
|
|
- {
|
|
|
- "imports": {
|
|
|
- "three": "https://unpkg.com/three@<version>/build/three.module.js"
|
|
|
- }
|
|
|
- }
|
|
|
- </script>
|
|
|
+ <p>命令行本地服务器通过终端窗口运行。可能需要先安装相关的编程语言。</p>
|
|
|
|
|
|
- <script type="module">
|
|
|
+ <ul>
|
|
|
+ <li><i>npx http-server</i> (Node.js)</li>
|
|
|
+ <li><i>npx five-server</i> (Node.js)</li>
|
|
|
+ <li><i>python -m SimpleHTTPServer</i> (Python 2.x)</li>
|
|
|
+ <li><i>python -m http.server</i> (Python 3.x)</li>
|
|
|
+ <li><i>php -S localhost:8000</i> (PHP 5.4+)</li>
|
|
|
+ </ul>
|
|
|
|
|
|
- import * as THREE from 'three';
|
|
|
|
|
|
- const scene = new THREE.Scene();
|
|
|
+ <h3>GUI</h3>
|
|
|
|
|
|
- </script>
|
|
|
- </code>
|
|
|
+ <p>GUI 本地服务器在计算机上以应用程序窗口的形式运行，并可以有一个用户界面。</p>
|
|
|
|
|
|
- <h2>Addons</h2>
|
|
|
+ <ul>
|
|
|
+ <li>[link:https://greggman.github.io/servez Servez]</li>
|
|
|
+ </ul>
|
|
|
|
|
|
- <p>
|
|
|
- three.js的核心专注于3D引擎最重要的组件。其它很多有用的组件 —— 如控制器（control）、加载器（loader）以及后期处理效果（post-processing effect） —— 是 [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] 目录的一部分。它们被称为“示例”，虽然你可以直接将它们拿来使用，但它们也需要重新混合以及定制。这些组件和 three.js 的核心保持同步，而 npm 上类似的第三方包则由不同的作者进行维护，可能不是最新的。
|
|
|
- </p>
|
|
|
+ <h3>代码编辑器的插件</h3>
|
|
|
|
|
|
- <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 ，请使用相同的 CDN 来安装其他组件：
|
|
|
- </p>
|
|
|
+ <p>有些代码编辑器的插件可以按需生成一个简单的服务器。</p>
|
|
|
|
|
|
- <code>
|
|
|
- <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">
|
|
|
+ <ul>
|
|
|
+ <li>Visual Studio Code：[link:https://marketplace.visualstudio.com/items?itemName=yandeu.five-server Five Server]</li>
|
|
|
+ <li>Visual Studio Code：[link:https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer Live Server]</li>
|
|
|
+ <li>Atom：[link:https://atom.io/packages/atom-live-server Live Server]</li>
|
|
|
+ </ul>
|
|
|
|
|
|
- import * as THREE from 'three';
|
|
|
- import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
|
|
|
|
|
|
- const controls = new OrbitControls( camera, renderer.domElement );
|
|
|
+ </details>
|
|
|
|
|
|
- </script>
|
|
|
- </code>
|
|
|
+ <h3>生产</h3>
|
|
|
|
|
|
<p>
|
|
|
- 所有文件使用相同版本是十分重要的。请勿从不同版本导入不同的示例，也不要使用与 three.js 本身版本不一致的示例。
|
|
|
+ 当你准备部署网络应用时，只需将源文件推送给网络托管服务提供商即可，无需构建或编译任何内容。这样做的坏处是，你需要注意根据应用程序所需的依赖项（以及依赖项的依赖项！）不断更新导入映射。如果托管你的依赖项的 CDN 暂时宕机，你的网站也会停止工作。
|
|
|
</p>
|
|
|
|
|
|
- <h2>兼容性</h2>
|
|
|
-
|
|
|
- <h3>CommonJS 导入</h3>
|
|
|
-
|
|
|
<p>
|
|
|
- 虽然现代的 JavaScript 打包器已经默认支持ES module，然而也有一些较旧的构建工具并不支持。对于这些情况，你或许可以对这些打包器进行配置，让它们能够理解 ES module 。例如，[link:http://browserify.org/ Browserify] 仅需 [link:https://github.com/babel/babelify babelify] 插件。
|
|
|
+ <i><b>重要提示：</b> 请将所有依赖项从同一版本的 three.js 导入，并从相同的 CDN 上获取。混合使用不同来源的文件可能导致包含重复代码，甚至以意想不到的方式破坏应用程序。</i>
|
|
|
</p>
|
|
|
|
|
|
- <h3>Import maps</h3>
|
|
|
+ <h2>附加组件（Addons）</h2>
|
|
|
|
|
|
<p>
|
|
|
- 和从静态主机或CDN来进行安装的方式相比，从npm安装时，导入的路径有所不同。我们意识到，对于使用两种不同方式的用户群体来说，这是一个人体工程学问题。使用构建工具与打包器的开发者更喜欢仅使用单独的包说明符（如'three'）而非相对路径，而<em>examples/</em>目录中的文件使用相对于 <em>three.module.js</em> 的引用并不符合这一期望。对于不使用构建工具的人（用于快速原型、学习或个人参考）来说，或许也会很反感这些相对导入。这些相对导入需要确定目录结构，并且比全局 <em>THREE.*</em> 命名空间更不宽容。
|
|
|
+ 开箱即用的 three.js 包含 3D 引擎的基本要素。而其他 three.js 组件，如控件（controls）、加载器（loaders）和后期处理效果（post-processing effects）则属于 [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm addons/] 目录的一部分。附加组件无需单独<i>安装</i>，但需要单独<i>导入</i>。
|
|
|
</p>
|
|
|
|
|
|
<p>
|
|
|
- 我们希望在 [link:https://github.com/WICG/import-maps import maps] 广泛可用时，能够移除这些相对路径，将它们替换为单独的包说明符，'three'。这更加符合构建工具对npm包的期望，且使得两种用户群体在导入文件时能够编写完全相同的代码。对于更偏向于避免使用构建工具的用户来说，一个简单的 JSON 映射即可将所有的导入都定向到一个 CDN 或是静态文件夹。通过实验，目前你可以通过一个 import map 的 polyfill，来尝试更简洁的导入，如 [link:https://glitch.com/edit/#!/three-import-map?path=index.html import map example] 示例中所示。
|
|
|
+ 下面的示例展示了如何导入 three.js 的 [page:OrbitControls] 和 [page:GLTFLoader] 附加组件。必要时每个附加组件的文档或示例中也会提及这一点。
|
|
|
</p>
|
|
|
|
|
|
- <h3>Node.js</h3>
|
|
|
+ <code>
|
|
|
+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();
|
|
|
+ </code>
|
|
|
|
|
|
<p>
|
|
|
- 由于 three.js 是为 Web 构建的, 因此它依赖于浏览器和 DOM 的 API ，但这些 API 在 Node.js 里不一定存在。这些问题中有的可以使用 [link:https://github.com/stackgl/headless-gl headless-gl] 等 shims 来解决，或者用自定义的替代方案来替换像 [page:TextureLoader] 这样的组件。其他 DOM API 可能与使用它们的代码强相关，因此将更难以解决。我们欢迎简单且易于维护的 pull request 来改进对 Node.js 的支持，但建议先打开问题来讨论您的改进。
|
|
|
+ 一些优秀的第三方项目也可用于 three.js。这些项目需要单独安装，请参见 [link:#manual/introduction/Libraries-and-Plugins 库和插件]。
|
|
|
</p>
|
|
|
|
|
|
+ <h2>下一步</h2>
|
|
|
+
|
|
|
<p>
|
|
|
- 确保在您的 package.json 文件中添加 { "type": "module" }，以在您的 Node.js 项目中启用 ES6 模块。
|
|
|
+ 是时候开始[link:#manual/zh/introduction/Creating-a-scene 创建一个场景]了。
|
|
|
</p>
|
|
|
|
|
|
</body>
|
ReBeX