v7 迁移指南

首先，PixiJS v7 是一个现代化版本，可以反映自六年前首次发布 PixiJS 以来生态系统的变化。浏览器已经变得更好，但 PixiJS 并没有真正利用一些新功能，比如fetch、Workers、现代 JavaScript 语言语法。此版本保持了大部分高级 DisplayObjects（例如 Sprite、Graphics、Mesh 等）的完整性。除了少数内容，此版本对大多数用户来说应该会影响中等或较低。

👋 放弃 Internet Explorer

Microsoft 已正式终止对 IE 的支持，因此我们决定跟进。由于 IE 与 Safari/Chrome/Firefox/Edge 和移动浏览器相比有些格格不入，因此我们简化了许多现代化。如果你需要 IE 支持，请考虑使用 Babel 或其他翻译堆栈工具。

🗑️ 删除 Polyfill

我们删除了捆绑的 Polyfill，例如 requestAnimationFrame 和 Promise。这些内容现在在浏览器中广泛可用。如果项目需要它们，则开发人员应包含他们需要的 Polyfill 以进行向后兼容。

💬 输出 ES2020（模块）和 ES2017（浏览器）

PixiJS 历史上仅发布 ES5（没有类！）。一种新的输出标准让我们得以使用我们之前无法使用的 ES2017 特性（例如，String.prototype.startsWith、Array.prototype.contains 等）。它不仅让代码更具可读性，而且输出也更漂亮。对于模块，我们正在输出 ES2020，其中包含语法，例如空值合并（??）。如果您的项目需要向后兼容性，您可以使用 Babel 来转换或使用垫片库。

🐭 用 EventSystem 替换 InteractionManager

InteractionManager 正变得复杂且难以维护。很少有核心团队成员能够理解该代码。我们决定转至 FederatedEvents，因为它简洁、更符合 DOM 且支持冒泡之类的操作。好消息是，您不必更改代码，因为它基本上是直接替换。我们已为 DisplayObject 添加了 addEventListener 和 removeEventListener API，这些 API 具有与 DOM 相同的签名，并且可以代替 on 和 off 使用。

📦 用 Assets 替换 Loader

类似地，我们一直在想移除 Loader，因为它采用的是旧方法（例如，XMLHttpRequest）。这从 resource-loader 中分支出来，后者已随 PixiJS 使用了很长时间。Loader 的原始设计灵感很大程度上源自 Flash/AS3，这现在看起来过时了。我们希望新迭代具备一些功能：静态加载、与 Workers 配合加载、后台加载、基于 Promise、更少的缓存层。以下是如何变更的快速示例

import { Loader, Sprite } from 'pixi.js';

const loader = new Loader();
loader.add('background', 'path/to/assets/background.jpg');
loader.load((loader, resources) => {
  const image = Sprite.from(resources.background.texture);
});

现在变成

import { Assets, Sprite } from 'pixi.js';

const texture = await Assets.load('path/to/assets/background.jpg');
const image = Sprite.from(texture);

🤝 放弃使用 peerDependencies

PixiJS 在每个包内的 package.json 中大量使用了 peerDependencies。这种设计选择给 Pixi 带来了很多问题。这是一个破坏性变更，所以现在是时候将其移除。我们已决定完全移除 peerDependencies，转而使用 无。这应让安装和升级 pixi.js 变得容易得多。我们正在更新 我们的工具 以便利用包来编写自定义版本。 编辑：从 7.2.0 起，我们已恢复此变更以保持与某些基于模块的 CDN 的兼容性。

👂 其他变更

• 已从所有包中移除浏览器构建，但 pixi.js 和 pixi.js-legacy 除外。
• 移除了 Graphics.nextRoundedRectBehavior，这现在是默认行为
• 删除 Text.nextLineHeightBehavior，现在是默认行为
• AbstractBatchRenderer 和 BatchPluginFactory 已被删除。扩展 BatchRenderer 或对默认 BatchRenderer 使用 setShaderGenerator（例如：renderer.plugins.batch）
• 不需再在 @pixi/core 中默认安装 BatchRenderer，也不需再使用 Renderer.registerPlugin('batch', BatchRenderer)

来自 @pixi/core 的导出

@pixi/core 软件包现在依赖并重新导出以下软件包。

• @pixi/math
• @pixi/contants
• @pixi/utils
• @pixi/runner
• @pixi/settings
• @pixi/ticker

尽管一些软件包在直接安装时仍然有效，但其他软件包却不行，这是因为在 @pixi/core 中安装软件包时，实际上会导入同一代码的两个副本。这会导致问题，比如无法通过 @pixi/settings 更改设置，这是因为 @pixi/core 有自身版本的该软件包。建议从项目中卸载这些软件包，并改用 @pixi/core。

import { Rectangle } from '@pixi/math';
import { settings } from '@pixi/settings';
import { ALPHA_MODES } from '@pixi/constants';
import { string2hex } from '@pixi/utils';

现在变成

import { Rectangle, settings, ALPHA_MODES, utils } from '@pixi/core';

const { string2hex } = utils;

提取和准备系统

提取和准备插件已转换为渲染器“系统”。

renderer.plugins.extract
renderer.plugins.prepare

现在变成

renderer.extract
renderer.prepare

扩展自安装

现在扩展会自安装，这意味着你只需要导入该类即可使用。例如，在 v6 中

import { AccessibilityManager } from '@pixi/accessibility';
import { extensions } from '@pixi/core';
extensions.add(AccessibilityManager);

现在变成

import '@pixi/accessibility';

使用碰撞检测与事件

使用新事件系统后，发生更改的一个常用 API 是 hitTest。

import {Application} from 'pixi.js';

const app = new Application();
app.renderer.plugins.interaction.hitTest({x, y});

现在变成

import {Application, EventBoundary} from 'pixi.js';

const app = new Application();
const boundary = new EventBoundary(app.stage);
boundary.hitTest(x, y);

新的异步提取方法

以下方法现在是异步的，并且返回一个 Promise。

• CanvasExtract.base64()
• CanvasExtract.image()
• Extract.base64()
• Extract.image()

import {Application, EventBoundary} from 'pixi.js';

const app = new Application();
const dataUri = app.renderer.extract.base64();

现在变成

import {Application, EventBoundary} from 'pixi.js';

const app = new Application();
const dataUri = await app.renderer.extract.base64();

互动移动事件

PixiJS 中的互动事件现在在 v7 中表现得像 DOM。这是有意为之，以便行为与开发人员熟悉的保持一致，但显然会影响具有 pointermove、mousemove 和 touchmove 行为。

与 DOM 类似，移动事件现在是本地的。这意味着如果你不在对象边界内，则不会收到移动事件。一般来说，你应当考虑将移动事件添加到舞台或父元素，而不是 DisplayObject 本身。

操作示例：https://jsfiddle.net/bigtimebuddy/spnv4wm6/

交互式属性处理器已移除

基于属性的处理器已从事件中移除。这是旧 InteractionManager 的一项功能。例如

sprite.pointertap = () => {
 // handler the pointertap
};

现在变成

sprite.on('pointertap', () => {
 // handler the pointertap
});

属性 buttonMode 已移除

属性 buttonMode 是在 pointer 和 null 之间切换 cursor 属性的一个便利功能。现在它已被移除。

sprite.buttonMode = true;

现在变成

sprite.cursor = 'pointer';

如果你想重新添加此功能，你可以修补 DisplayObject 的原型

import { DisplayObject } from 'pixi.js';

Object.defineProperty(DisplayObject.prototype, 'buttonMode', {
  get() { return this.cursor === 'pointer'; },
  set(value) { this.cursor = value ? 'pointer' : null; },
});

☝️ 升级建议

如果你计划将你的代码从 v6 过渡，在升级到 v7 之前先实现 v6 中一些更重大的更改会很有帮助

• 更新到最新的 v6.5.x
• 切换到事件包，通过安装 @pixi/events 和替换 InteractionManager

import { InteractionManager, extensions, Application } from 'pixi.js';
import { EventSystem } from '@pixi/events';

// Uninstall interaction
extensions.remove(InteractionManager);

// Create the renderer or application
const app = new Application();

// Install events
app.renderer.addSystem(EventSystem, 'events');

• 通过安装 @pixi/assets 并替换 Loader，来切换到资源包。有关实施资源的更多信息，请参阅此指南。
• 设置 Graphics.nextRoundedRectBehavior = true，这会对圆角半径使用弧，而不是贝塞尔曲线。
• 设置 Text.nextLineHeightBehavior = true，这会将行高设为类似 DOM 的默认值。

🏗️ 插件支持

插件	兼容	支持的插件版本
PixiJS Sound	✅	v5.0.0+
PixiJS HTMLText	✅	v3.0.0+
PixiJS Filters	✅	v5.0.0+
PixiJS GIF	✅	v2.0.0+
PixiJS Spine	✅	v4.0.0+
PixiJS Particle Emitter	✅	v5.0.8+
PixiJS Animate	❌
PixiJS Layers	✅	v2.0.0+
PixiJS Lights	✅	v4.0.0+
PixiJS Graphics Smooth	✅	v1.0.0+
PixiJS Tilemap	❌