v7 迁移指南

🌐 v7 Migration Guide

首先，PixiJS v7 是一次现代化的发布，反映了自 PixiJS 六年前首次发布以来生态系统的变化。浏览器变得更好了，但 PixiJS 并没有真正利用一些新功能，比如 fetch、Workers 和现代 JavaScript 语言语法。此次发布保留了大部分高级 DisplayObjects（例如 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

🌐 👋 Dropping Internet Explorer

微软已正式终止对 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.

🗑️ 移除 Polyfills

🌐 🗑️ Remove Polyfills

我们移除了打包的填充，如 requestAnimationFrame 和 Promise。这些功能现在在浏览器中已广泛可用。如果项目需要它们，开发者应自行包含其所需的填充以保证向后兼容性。

🌐 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.

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

🌐 💬 Output ES2020 (modules) and ES2017 (browser)

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.

🐭 将 InteractionManager 替换为 EventSystem

🌐 🐭 Replaces InteractionManager with EventSystem

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.

📦 用资源替换加载器

🌐 📦 Replaces Loader with Assets

同样地，我们一直想要移除 Loader，因为它采用了过时的方法（例如，XMLHttpRequest）。它是从 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);

🤝 放弃使用 peerDependencies

🌐 🤝 Abandon the use of peerDependencies

PixiJS 在每个包的 package.json 中大量使用 peerDependencies。这个设计选择给 Pixi 带来了许多问题。移除它是一个重大更改，所以现在是一个好时机。我们决定完全移除 peerDependencies，而选择 不使用任何东西。这应该会使安装和升级 pixi.js 更加容易。我们正在更新我们的工具，以便使用这些包来组合自定义版本。 编辑：从 7.2.0 版本开始，我们已经撤销了此更改，以保持与一些基于模块的 CDN 的兼容性。

👂 其他更改

🌐 👂 Other Changes

除了 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` 的导出

🌐 Exports from @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;

提取和准备系统

🌐 Extract and Prepare Systems

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

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

renderer.plugins.extract;
renderer.plugins.prepare;

现在变成：

🌐 Now becomes:

renderer.extract;
renderer.prepare;

扩展自安装

🌐 Extensions Self-Install

扩展现在会自行安装，因此你只需要导入类即可使用。例如，在 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 与事件结合使用

🌐 Using hitTest with Events

在新的事件系统中，更改的常见 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:

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

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

新的异步提取方法

🌐 New Async Extract Methods

以下方法现在是异步的并返回 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:

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

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

互动移动事件

🌐 Interactive Move Events

PixiJS 中的交互事件在 v7 中现在的行为像 DOM。这是为了让开发者熟悉的行为而有意为之，但显然会影响 pointermove、mousemove 和 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.

像 DOM 一样，移动事件现在是_局部的_。这意味着如果你位于对象的范围之外，你将不会接收到移动事件。通常，你应该考虑将移动事件添加到舞台或父级，而不是 DisplayObject 本身。

🌐 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.

工作示例: https://jsfiddle.net/bigtimebuddy/spnv4wm6/

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

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

🌐 Interactive Property Handlers are Removed

基于属性的处理程序已从事件中移除。这是旧版 InteractionManager 的一个特性。例如：

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

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

现在变成：

🌐 Now becomes:

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

属性 `buttonMode` 已被移除

🌐 Property buttonMode has been removed

属性 buttonMode 原本是用于在 pointer 和 null 之间切换 cursor 属性的便利功能。它现在已经被移除。

🌐 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:

sprite.cursor = 'pointer';

如果你想重新添加此功能，你可以修补 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;
  },
});

☝️ 升级建议

🌐 ☝️ Suggestions for Upgrading

如果你计划从 v6 过渡代码，那么在升级到 v7 之前首先在 v6 中实现一些更显着的更改会很有帮助：

🌐 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:

更新到最新的 v6.5.x
通过安装 @pixi/events 并替换 InteractionManager，切换到 Events 包。

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 来切换到 Assets 包。有关实现 Assets 的更多信息，请参见此指南。
设置 Graphics.nextRoundedRectBehavior = true，这使用圆弧来表示圆角半径，而不是贝塞尔曲线。
设置 Text.nextLineHeightBehavior = true，默认情况下，这会采用类似 DOM 的行高行为。

🏗️ 支持插件

🌐 🏗️ Plugin Supported

插件	兼容	支持的插件版本
[PixiJS 声音]（https://github.com/pixijs/sound）	✅	v5.0.0+
[PixiJS HTMLText]（https://github.com/pixijs/html-text）	✅	v3.0.0+
[PixiJS 过滤]（https://github.com/pixijs/filters）	✅	v5.0.0+
[PixiJS 动图]（https://github.com/pixijs/gif）	✅	v2.0.0+
[PixiJS 脊柱]（https://github.com/pixijs/spine）	✅	v4.0.0+
[PixiJS 粒子触发器]（https://github.com/pixijs/particle-emitter）	✅	v5.0.8+
[PixiJS 动画]（https://github.com/pixijs/animate）	❌
[PixiJS 图层]（https://github.com/pixijs/layers）	✅	v2.0.0+
[PixiJS 灯光]（https://github.com/pixijs/lights）	✅	v4.0.0+
[PixiJS 图形流畅]（https://github.com/pixijs/graphics-smooth）	✅	v1.0.0+
[PixiJS 瓦片地图]（https://github.com/pixijs/tilemap）	❌

👋 放弃 Internet Explorer​

🗑️ 移除 Polyfills​

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

🐭 将 InteractionManager 替换为 EventSystem​

📦 用资源替换加载器​

🤝 放弃使用 peerDependencies​

👂 其他更改​

@pixi/core 的导出​

提取和准备系统​

扩展自安装​

将 hitTest 与事件结合使用​

新的异步提取方法​

互动移动事件​

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

属性 buttonMode 已被移除​

☝️ 升级建议​

🏗️ 支持插件​

👋 放弃 Internet Explorer

🗑️ 移除 Polyfills

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

🐭 将 InteractionManager 替换为 EventSystem

📦 用资源替换加载器

🤝 放弃使用 peerDependencies

👂 其他更改

`@pixi/core` 的导出

提取和准备系统

扩展自安装

将 hitTest 与事件结合使用

新的异步提取方法

互动移动事件

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

属性 `buttonMode` 已被移除

☝️ 升级建议

🏗️ 支持插件