编写 JavaScript 库

本简短教程将指导你如何为 Wonderland Engine 创建和共享组件库。

安装 npm 

npm 是 JavaScript 生态系统的官方包管理工具。

它现在已成为 Wonderland Engine 工具链的一部分，让开发者能够无缝使用外部依赖。 作为库的创建者，你需要 npm 来管理和发布你的库。

你可以下载带有 npm 安装包的 nodejs。

创建库 

在本教程中，我们将在一个名为 my-library 的文件夹中创建一个库。切换到 my-library 文件夹并运行：

npm init

一些提示将会出现，询问你关于包的信息：

package name: (my-library)
version: (1.0.0)

填写提示后，你将看到一个 package.json 文件，看起来像这样：

{
  "name": "my-library",
  "version": "1.0.0",
  "description": "我的 Wonderland Engine 第一个库！",
  "main": "index.js"
}

package.json 文件包含关于库的所有必要信息。当开发者安装你的库时，npm 会在此文件中找到所需的数据。

‘wonderlandengine’ 标签 

Wonderland Editor 基于一个特定的元标签自动注册库：wonderlandengine。

在为 Wonderland Engine 创建库时，你必须在 package.json 中添加以下行，例如，在 "main": "index.js" 之上：

  "wonderlandengine": {},

目前，这就是编辑器自动识别库所需的全部。未来，wonderlandengine 元数据对象可能会允许为 Wonderland Engine 指定更多属性。

入口点 

最重要的部分之一是 index.js 字段。它指定了应该导出你的库对象的文件。当开发者使用你的库并导入它时：

import {ComponentA, ComponentB} from 'my-library';

'my-library' 解析为：

node_modules/my-library/index.js

因此，入口点必须导出你的库的公共接口（类、函数等）：

index.js

// 从其他文件重新导出组件
export {ComponentA} from './component-a.js';
export {ComponentB} from './component-b.js';

export {someUtilityFunction} from './someUtilityFunction.js';

当在 package.json 中找到 wonderlandengine 元标签时，入口点用于查找所有导出的组件（在上面的例子中是 ComponentA 和 ComponentB）。

依赖 

在本教程中，我们将创建一个使用 Wonderland Engine 公共 API 的组件。

我们在 package.json 中将其添加为依赖项。在 "dependencies" 下面，我们添加一个新的 "peerDependencies" 部分：

  "dependencies": {
  },
  "peerDependencies": {
    "@wonderlandengine/api": "^1.0.0"
  }

这很重要，因为我们希望允许用户在与库兼容的范围内使用多个 API 版本，通常最多到下一个主要版本。

为了能够使用 API，你接下来需要运行 npm install 来应用对 package.json 的更改：

npm install

添加内容 

在本教程中，我们将创建一个简单的组件，使其对象以某个速度向前移动。在库文件夹中创建一个名为 move-forward.js 的新文件，内容如下：

move-forward.js

import {Component, Property} from '@wonderlandengine/api';

const tempVec = new Float32Array(3);

export class MoveForward extends Component {
    static TypeName = 'move-forward';
    static Properties = {
        speed: Property.float(1.5),
    };

    update(dt) {
        this.object.getForward(tempVec);

        tempVec[0] *= this.speed;
        tempVec[1] *= this.speed;
        tempVec[2] *= this.speed;

        this.object.translate(tempVec);
    }
}

我们还需要重新导出这个组件给使用我们包的开发者。我们可以更新 index.js 文件为：

index.js

export {MoveForward} from './move-forward.js';

对于这个示例，我们可以直接将组件放在 index.js 中。但是，当你的库变得越来越大时，你希望对你的导出有更大的控制。

测试与调试 

测试可以通过创建一个 Wonderland Engine 项目并使用本地路径安装你的库来进行。 在本教程中，我们假设已经创建了一个名为 MyWonderland 的 Wonderland Engine 项目。 在项目的根目录，你可以运行：

npm install path/to/my-library

你需要将 path/to/my-library 替换为指向库文件夹根目录的路径。

这样就完成了！你现在应该可以在你的项目中访问 MoveForward 组件。

Wonderland Engine 编辑器具有我们 move-forward 组件

在这种情况下，库是本地安装的。其他开发者将无法访问该库。你需要：

  • 发布库（如 发布库 部分所述）
  • 或提供一个本地包（例如，作为 .tar.gz 文件）供他们安装

发布库 

通过在 npm 包存储库中发布库作为一个包，你可以为代码标记一个特定的版本号，并将包上传到 npm 服务器，以供其他开发者下载。

登录 

要将库发布到 npm，你需要：

发布 

登录后，你可以通过使用终端导航到库文件夹并运行以下命令来发布你的包：

npm run publish

你还可以运行一个“干运行”发布：

npm run publish --dry-run

此命令将打印有关将要发布的文件的信息，并允许验证你没有发布不需要的文件。

安装 

成功发布你的库后，你可以在你的项目中运行以下命令来安装它：

npm install --save my-library

你现在已准备好创建最精彩的库。

创建库有助于社区繁荣并为所有人开发惊人的 WebXR 内容。

Writing Components in Typescript