Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: Improve Chinese translation. #26945

Merged
merged 1 commit into from
Oct 11, 2023
Merged

Docs: Improve Chinese translation. #26945

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
278 changes: 191 additions & 87 deletions docs/manual/zh/introduction/Installation.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
&lt;!DOCTYPE html&gt;
&lt;html lang="en"&gt;
&lt;head&gt;
&lt;meta charset="utf-8"&gt;
&lt;title&gt;My first three.js app&lt;/title&gt;
&lt;style&gt;
body { margin: 0; }
&lt;/style&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;script type="module" src="/main.js"&gt;&lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;
</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>&lt;head>&lt/head></i> 标签内、样式（styles）之后。
</p>
<code>
&lt;script type="importmap">
{
"imports": {
"three": "https://unpkg.com/three@&lt;version&gt;/build/three.module.js",
"three/addons/": "https://unpkg.com/three@&lt;version&gt;/examples/jsm/"
}
}
&lt;/script>
</code>
<p>
不要忘记将上述链接中的 <i>&lt;version&gt;</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>
&lt;script type="importmap">
{
"imports": {
"three": "https://unpkg.com/three@&lt;version&gt;/build/three.module.js"
}
}
&lt;/script>
<p>命令行本地服务器通过终端窗口运行。可能需要先安装相关的编程语言。</p>

&lt;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>

&lt;/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>
&lt;script type="importmap">
{
"imports": {
"three": "https://unpkg.com/three@&lt;version&gt;/build/three.module.js",
"three/addons/": "https://unpkg.com/three@&lt;version&gt;/examples/jsm/"
}
}
&lt;/script>

&lt;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>

&lt;/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>
Expand Down