v7 迁移指南

首先，PixiJS v7 是一个现代化版本，反映了自 PixiJS 六年多前首次发布以来生态系统的变化。浏览器已经变得更好，但 PixiJS 还没有真正利用一些新功能，如 fetch、Workers、现代 JavaScript 语言语法。此版本保留了大部分高级显示对象（例如 Sprite、Graphics、Mesh 等）。除了一些事情之外，此版本对于大多数用户来说应该是中度到低度的影响。

英：First and foremost, PixiJS v7 is a modernization release that reflects changes in the ecosystem since PixiJS was first published over six years ago. Browsers have gotten better, but PixiJS hasn't really taken advantage of some of the new features like fetch, Workers, modern JavaScript language syntax. This release keeps intact much of the high-level DisplayObjects (e.g., Sprite, Graphics, Mesh, etc). Aside from a few things, this release should be medium to low impact for most users.

👋 放弃 Internet Explorer

Microsoft 正式终止了对 IE 的支持，因此我们决定效仿。它简化了我们的许多现代化工作，因为 IE 是 Safari/Chrome/Firefox/Edge 和移动浏览器的概述。如果你需要 IE 支持，请考虑使用 Babel 或其他编译工具。

英：Microsoft officially ended support for IE, so we decided to follow. It simplified many of our modernizations since IE was an outliner from Safari/Chrome/Firefox/Edge and mobile browsers. If you need support for IE, please consider using Babel or some other trans-piling tool.

🗑️ 删除 Polyfill

我们删除了打包的 Polyfill，例如 requestAnimationFrame 和 Promise。这些东西现在在浏览器中广泛使用。如果项目需要它们，开发者应该包含向后兼容所需的 Polyfill。请查看 polyfill.io。

英：We removed the bundled polyfills such as requestAnimationFrame and Promise. These things are widely available in browsers now. If projects require them, developers should include the polyfills they need for backward-compatibility. Please check out polyfill.io.

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

PixiJS 历史上只发布了 ES5（没有类！）。新的输出标准允许我们使用以前无法使用的 ES2017 功能（例如 String.prototype.startsWith、Array.prototype.contains 等）。它不仅使代码更具可读性，而且输出看起来也更好。对于模块，我们输出 ES2020，其中包含类似空值合并 (??) 的语法。如果你的项目需要向后兼容，你可以使用 Babel 进行转译或填充。

英：PixiJS historically only published ES5 (no classes!). A new output standard allows us to use ES2017 features that previously we couldn't use (e.g., String.prototype.startsWith, Array.prototype.contains, etc). Not only does it make the code more readable, but the output looks nicer as well. For modules we are outputting ES2020, which contains syntax like nullish coalescing (??). If your project needs to have backward compatibility, you can use Babel to transpile or polyfill.

🐭 用 EventSystem 替换 InteractionManager

InteractionManager 变得越来越复杂并且难以维护。很少有核心团队成员理解代码。我们决定转向 FederatedEvents，它简洁、与 DOM 更好地保持一致，并且支持冒泡等功能。好消息是你不必更改代码，因为它很大程度上是直接替换。我们向 DisplayObject 添加了 addEventListener 和 removeEventListener API，它们具有相同的 DOM 签名，可以用来代替 on 和 off。

英：InteractionManager was getting complex and difficult to maintain. Few core team members understood the code. We decided to move to FederatedEvents, which is concise, better aligned with the DOM, and supports things like bubbling. The good news, is you shouldn't have to change code, as it is largely a drop-in replacement. We added addEventListener and removeEventListener APIs to DisplayObject which have the same DOM signature and can be used instead of on and off.

📦 用资源替换加载器

同样，我们一直希望删除 Loader，因为它的旧版方法（例如 XMLHttpRequest）。这是从 resource-loader 分叉出来的，该 resource-loader 已经与 PixiJS 合作很长时间了。 Loader 最初的设计灵感主要是由 Flash/AS3 驱动的，现在看来已经过时了。我们希望从新的迭代中得到一些东西：静态加载、使用 Workers 加载、后台加载、基于 Promise、更少的缓存层。下面是一个简单的示例，说明了这种情况将如何改变：

英：Similarly, we've been wanting to remove the Loader because of its legacy approach (e.g., XMLHttpRequest). This was forked from resource-loader that has been with PixiJS for a long time. The original design inspiration for Loader was driven largely by Flash/AS3, which now seem dated. There were a few things we wanted out of a new iteration: static loading, loading with Workers, background loading, Promise-based, fewer layers of caching. Here's a quick example of how this will change:

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);
});

现在变成：

英：Now becomes:

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

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

🤝 放弃使用 peerDependency

PixiJS 在每个包的 package.json 中大量使用 peerDependencies。这种设计选择给 Pixi 带来了许多问题。删除这是一个重大更改，所以现在是个好时机。我们决定完全删除 peerDependencies，而不是选择什么都不做。这将使 pixi.js 的安装和升级变得更加容易。我们正在努力更新我们的工具，以便用包编写自定义版本。 编辑：从 7.2.0 开始，我们已恢复此更改以保持与某些基于模块的 CDN 的兼容性。

英：PixiJS heavily uses peerDependencies in the package.json within each package. This design choice has plagued Pixi with many issues. It's a breaking change to remove, so now was a good time. We have decided to completely remove peerDependencies, instead opting for nothing. This should make installing and upgrading pixi.js much easier. We are working on updating our tooling for composing a custom version with packages. Edit: As of 7.2.0, we have reverted this change to keep compatibility with some module-based CDNs.

👂 其他变化

除 pixi.js 和 pixi.js-legacy 外，所有软件包的浏览器版本均已删除。
删除 Graphics.nextRoundedRectBehavior，这是现在的默认行为
删除 Text.nextLineHeightBehavior，这是现在的默认行为
AbstractBatchRenderer 和 BatchPluginFactory 已被删除。扩展 BatchRenderer 或在默认 BatchRenderer 上使用 setShaderGenerator（例如 renderer.plugins.batch）
BatchRenderer 在 @pixi/core 中默认安装，不再需要 Renderer.registerPlugin('batch', BatchRenderer)

从 `@pixi/core` 导出

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

英：The @pixi/core package now depends and re-exports the following packages.

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

虽然有些软件包在直接安装时仍然可以工作，但其他软件包则不能，因为通过将它们与 @pixi/core 一起安装，你将有效地导入相同代码的两个副本。这将导致错误，从 @pixi/settings 更改设置不会执行任何操作，因为 @pixi/core 有自己的该软件包版本。建议你从项目中卸载这些并使用 @pixi/core 代替。

英：While some packages will still work when installed directly, others will not, since by installing them alongside @pixi/core you will be effectively importing two copies of the same code. This will lead to errors where changing settings from @pixi/settings doesn't do anything since @pixi/core has its own version of that package. It is recommended that you uninstall these from your project and use @pixi/core instead.

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

现在变成：

英：Now becomes:

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

const { string2hex } = utils;

提取和准备系统

提取和准备插件已转换为渲染器 "systems"。

英：Extract and prepare plugins have been converted to Renderer "systems".

renderer.plugins.extract
renderer.plugins.prepare

现在变成：

英：Now becomes:

renderer.extract
renderer.prepare

扩展自安装

扩展现在会自行安装，因此你只需导入该类即可使用。例如，在 v6 中：

英：Extensions now install themselves, so you should only need to import the class in order to use. For example, in v6:

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

现在变成：

英：Now becomes:

import '@pixi/accessibility';

将 hitTest 与事件结合使用

使用新的事件系统，更改的常见 API 之一是 `hitTest.

英：With the new events system, one of the common APIs that changed is `hitTest.

import {Application} from 'pixi.js';

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

Now becomes:

英：Now becomes:

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

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

新的异步提取方法

The following methods are now async and return a Promise.

英：The following methods are now async and return a 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();

Now becomes:

英：Now becomes:

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

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

互动移动事件

Interaction events in PixiJS now behave like the DOM in v7. This was intentional to align around behavior that would be familiar with developers, but obviously impacts the behavior with pointermove, mousemove, and touchmove.

英：Interaction events in PixiJS now behave like the DOM in v7. This was intentional to align around behavior that would be familiar with developers, but obviously impacts the behavior with pointermove, mousemove, and touchmove.

Like the DOM, move events are now local. This means that if you are outside the bounds of the object, you will not receive a move event. Generally, you should consider adding move events to the stage or parent instead of the DisplayObject itself.

英：Like the DOM, move events are now local. This means that if you are outside the bounds of the object, you will not receive a move event. Generally, you should consider adding move events to the stage or parent instead of the DisplayObject itself.

Working example: https://jsfiddle.net/bigtimebuddy/spnv4wm6/

英：Working example: https://jsfiddle.net/bigtimebuddy/spnv4wm6/

交互式属性处理程序被删除

Property-based handlers were removed from events. This was a feature of the old InteractionManager. For instance:

英：Property-based handlers were removed from events. This was a feature of the old InteractionManager. For instance:

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

Now becomes:

英：Now becomes:

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

属性 `buttonMode` 已被删除

The property buttonMode was a convenience for toggling the cursor property between pointer and null. It has now been removed.

英：The property buttonMode was a convenience for toggling the cursor property between pointer and null. It has now been removed.

sprite.buttonMode = true;

Now becomes:

英：Now becomes:

sprite.cursor = 'pointer';

If you would like to re-add this functionality, you can 修补 DisplayObject 的原型:

英：If you would like to re-add this functionality, you can patch DisplayObject's prototype:

import { DisplayObject } from 'pixi.js';

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

☝️升级建议

If you're planning on transitioning your code from v6, it would be helpful to implement some of the more dramatic changes in v6 first before upgrading to v7:

英：If you're planning on transitioning your code from v6, it would be helpful to implement some of the more dramatic changes in v6 first before upgrading to v7:

Update to the latest v6.5.x
切换到事件包 by installing @pixi/events and swapping 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');

Switch to the Assets package by installing @pixi/assets and swapping for Loader. For more information on implementing Assets, see 本指南.
Set Graphics.nextRoundedRectBehavior = true, this uses arcs for corner radius instead of bezier curves.
Set Text.nextLineHeightBehavior = true，这默认为行高的类似 DOM 的行为。

🏗️ 支持插件

插件	兼容的	支持的插件版本
PixiJS 声音	✅	v5.0.0+
PixiJS HTML 文本	✅	v3.0.0+
PixiJS 过滤器	✅	v5.0.0+
PixiJS GIF	✅	v2.0.0+
PixiJS Spine	✅	v4.0.0+
PixiJS 粒子触发器	✅	v5.0.8+
PixiJS 动画	❌
PixiJS 层	✅	v2.0.0+
PixiJS 灯	✅	v4.0.0+
PixiJS 图形平滑	✅	v1.0.0+
PixiJS Tilemap	❌

v7 迁移指南

👋 放弃 Internet Explorer​

🗑️ 删除 Polyfill​

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

🐭 用 EventSystem 替换 InteractionManager​

📦 用资源替换加载器​

🤝 放弃使用 peerDependency​

👂 其他变化​

从 @pixi/core 导出​

提取和准备系统​

扩展自安装​

将 hitTest 与事件结合使用​

新的异步提取方法​

互动移动事件​

交互式属性处理程序被删除​

属性 buttonMode 已被删除​

☝️升级建议​

🏗️ 支持插件​

👋 放弃 Internet Explorer

🗑️ 删除 Polyfill

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

🐭 用 EventSystem 替换 InteractionManager

📦 用资源替换加载器

🤝 放弃使用 peerDependency

👂 其他变化

从 `@pixi/core` 导出

提取和准备系统

扩展自安装

将 hitTest 与事件结合使用

新的异步提取方法

互动移动事件

交互式属性处理程序被删除

属性 `buttonMode` 已被删除

☝️升级建议

🏗️ 支持插件