Skip to main content

v7 迁移指南

¥v7 Migration Guide

首先,PixiJS v7 是一个现代化版本,反映了自 PixiJS 六年多前首次发布以来生态系统的变化。浏览器已经变得更好,但 PixiJS 还没有真正利用一些新功能,如 fetchWorkers、现代 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

¥👋 Dropping 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

¥🗑️ Remove Polyfills

我们删除了打包的 Polyfill,例如 requestAnimationFramePromise。这些东西现在在浏览器中广泛使用。如果项目需要它们,开发者应该包含向后兼容所需的 Polyfill。

¥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.startsWithArray.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

¥🐭 Replaces InteractionManager with EventSystem

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

¥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 复刻出来的,该 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

¥🤝 Abandon the use of peerDependencies

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. 编辑:从 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.

👂 其他变化

¥👂 Other Changes

  • pixi.jspixi.js-legacy 外,所有软件包的浏览器版本均已删除。

    ¥Browser builds have been removed for all packages, with the exception of pixi.js and pixi.js-legacy.

  • 删除 Graphics.nextRoundedRectBehavior,这是现在的默认行为

    ¥Removes Graphics.nextRoundedRectBehavior this is now the default behavior

  • 删除 Text.nextLineHeightBehavior,这是现在的默认行为

    ¥Removes Text.nextLineHeightBehavior this is now the default behavior

  • AbstractBatchRendererBatchPluginFactory 已被删除。扩展 BatchRenderer 或在默认 BatchRenderer 上使用 setShaderGenerator(例如 renderer.plugins.batch

    ¥AbstractBatchRenderer and BatchPluginFactory has been removed. Either extends BatchRenderer or use setShaderGenerator on the default BatchRenderer, (e.g., renderer.plugins.batch)

  • BatchRenderer 在 @pixi/core 中默认安装,不再需要 Renderer.registerPlugin('batch', BatchRenderer)

    ¥BatchRenderer is installed by default in @pixi/core, no need to Renderer.registerPlugin('batch', BatchRenderer) anymore

@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

提取和准备插件已转换为渲染器 "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。这是有意为了使开发者熟悉的行为保持一致,但显然会影响 pointermovemousemovetouchmove 的行为。

¥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 可以方便地在 pointernull 之间切换 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:

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 包。有关实现资源的更多信息,请参阅 本指南

    ¥Switch to the Assets package by installing @pixi/assets and swapping for Loader. For more information on implementing Assets, see this guide.

  • 设置 Graphics.nextRoundedRectBehavior = true,这使用圆弧作为角半径而不是贝塞尔曲线。

    ¥Set Graphics.nextRoundedRectBehavior = true, this uses arcs for corner radius instead of bezier curves.

  • 设置 Text.nextLineHeightBehavior = true,这默认为行高的类似 DOM 的行为。

    ¥Set Text.nextLineHeightBehavior = true, this defaults to the DOM-like behavior for line height.

🏗️ 支持插件

¥🏗️ Plugin Supported

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