Skip to main content

v5 迁移指南

¥v5 Migration Guide

本文档对于尝试从 v4 升级到 v5 的开发者非常有用。这包括陷阱和重要上下文，用于理解为什么 v4 代码需要一些细微的更改。一般来说，我们尝试在 v5 中向后兼容 console 中弃用警告的使用。然而，有时变化太大，需要一些额外的帮助。

¥This document is useful for developers who are attempting to upgrading from v4 to v5. This includes gotchas and important context for understanding why your v4 code made need some subtle changes. In general, we've try to be as backward-compatible in v5 with the use of deprecation warnings in the console. There are, however, sometimes when changes are too substantial and require some additional help.

🚧 API 变更​

¥🚧 API Changes

打造一流的 WebGL​

¥Making WebGL First-Class

PixiJS v5 使 WebGL 成为一流渲染器，并使 CanvasRenderer 成为二流渲染器。从功能上来说，v4 没有太大变化，但有一些微妙的内部命名更改可能会阻碍一些开发者升级到 v5。例如：

¥PixiJS v5 has made WebGL the first-class renderer and made CanvasRenderer to be second-class. Functionally, there's not much that changed from v4, but there are a bunch of subtle internal naming changes which could trip-up some developers upgrading to v5. For instance:

  • WebGLRenderer 变成 Renderer

    ¥WebGLRenderer becomes Renderer

  • renderWebGL 变成 render（在 DisplayObject、Sprite、Container 等中）

    ¥renderWebGL becomes render (in DisplayObject, Sprite, Container, etc)

  • _renderWebGL 变成 _render（在 DisplayObject、Container 等中）

    ¥_renderWebGL becomes _render (in DisplayObject, Container, etc)

如果你创建的插件或项目之前在容器上使用了 render（请参阅 #5510），这可能会导致你的项目无法正确渲染。请考虑将用户定义的 render 重命名为其他名称。在大多数其他情况下，当你尝试调用与 WebGL 相关的类或方法（例如 new PIXI.WebGLRenderer()）时，你会收到弃用警告。

¥If you created a plugin or project that previously used render on a Container (see #5510), this will probably cause your project to not render correctly. Please consider renaming your user-defined render to something else. In most other cases, you'll get a deprecation warning trying to invoke WebGL-related classes or methods, e.g., new PIXI.WebGLRenderer().

渲染器参数​

¥Renderer Parameters

在 Renderer 构造函数中指定 options 作为第三个参数已正式删除（与 PIXI.Application、PIXI.autoDetectRenderer 和 PIXI.CanvasRenderer 相同）。在 v4 中我们支持两个函数签名，但在 v5 中我们放弃了 width, height, options 签名。请将 width 和 height 添加到 options。

¥Specifying options as a third parameter in Renderer constructor is officially dropped (same with PIXI.Application, PIXI.autoDetectRenderer & PIXI.CanvasRenderer). In v4 we supported two function signatures, but in v5 we dropped width, height, options signature. Please add width and height to options.

const renderer = new PIXI.Renderer(800, 600, { transparent: true }); // bad
const renderer = new PIXI.Renderer({ width: 800, height: 600, transparent: true }); // good

  • 注意：在渲染器或应用构造函数选项中添加 transparent: true 可能有助于解决某些设备上的奇怪问题，但可能会降低 FPS。比 preserveDrawingBuffer: true 好多了。

    ¥Note: Adding transparent: true in Renderer or Application constructor options might help with strange artifacts on some devices, but it might reduce FPS. It's much better than preserveDrawingBuffer: true.

  • 如果你需要使用 css 像素调整画布大小的 v4 默认行为，请将 autoDensity: true 添加到选项中。

    ¥If you need the v4 default behavior of resizing the canvas using css pixels, add autoDensity: true to the options.

并非所有内容都进入参数。即使 WebGL2 可用，也要启用 WebGL1，请使用

¥Not everything went to params. To enable WebGL1 even if WebGL2 is available, use

PIXI.settings.PREFER_ENV = PIXI.ENV.WEBGL;

网状、扁平、绳索​

¥Mesh, Plane, Rope

PixiJS v5 引入了一个名为 PIXI.Mesh 的新类。这允许覆盖默认着色器并能够向几何体添加更多属性。对于 example，你可以向顶点添加颜色。

¥PixiJS v5 introduces a new class called PIXI.Mesh. This allows overriding the default shader and the ability to add more attributes to geometry. For example, you can add colors to vertices.

旧的 v4 Mesh 类已从 PIXI.mesh.Mesh 移动到 PIXI.SimpleMesh，它扩展了 PIXI.Mesh。

¥The old v4 Mesh class has moved from PIXI.mesh.Mesh to PIXI.SimpleMesh, it extends PIXI.Mesh.

PIXI.mesh.Rope、PIXI.mesh.Plane、PIXI.mesh.NineSlicePlane 已分别移至 PIXI.SimpleRope、PIXI.SimplePlane 和 PIXI.NineSlicePlane。

¥PIXI.mesh.Rope, PIXI.mesh.Plane, PIXI.mesh.NineSlicePlane have moved to PIXI.SimpleRope, PIXI.SimplePlane and PIXI.NineSlicePlane respectively.

如果你在 v4 中使用自定义着色器或生成的网格，你可能会受到 v5 中这些更改的影响。

¥If you used custom shaders or generated meshes in v4, you might be impacted by these changes in v5.

PIXI.SimpleMesh 字段 vertices、uvs、indices 封装在 mesh.geometry 属性 buffers 内。例如，这是通过 mesh.uvBuffer 属性提供的缓冲区访问方式：

¥PIXI.SimpleMesh fields vertices, uvs, indices are wrapped inside mesh.geometry attribute buffers. For example, this is how access to buffers provided through mesh.uvBuffer property:

get uvBuffer()
{
    return this.geometry.buffers[1];
}

indices 属性快捷方式也丢失了，但你可以访问 mesh.geometry.indexBuffer 内的数据。

¥The indices property shortcut is also missing, but you can access the data inside mesh.geometry.indexBuffer.

你可以覆盖缓冲区数据，并通知它数据已更改，在这种情况下缓冲区将延迟上传到 GPU。之前在 v4 中，网格有几个标志来指示哪些属性必须更新，并且它们的名称会让人困惑。

¥You can override buffer data, and notify it that data was changed, in this case buffer will be uploaded to GPU lazily. Previously in v4 mesh had several flags that indicated which attributes have to be updated and their names confused people.

图形孔​

¥Graphics Holes

在 v4 中，图形中的绘制孔非常有限。这仅支持非形状绘制，例如使用 lineTo、bezierCurveTo 等。在 v5 中，我们通过支持形状改进了孔 API。不幸的是，没有支持 v4 API 的弃用策略。例如，在 v4 中：

¥Drawing holes in Graphics was very limited in v4. This only supported non-Shape drawing, like using lineTo, bezierCurveTo, etc. In v5, we improved the hole API by supporting shapes. Unfortunately, there's no deprecation strategy to support the v4 API. For instance, in v4:

const graphic = new PIXI.Graphics()
  .beginFill(0xff0000)
  .moveTo(0, 0)
  .lineTo(100, 0)
  .lineTo(100, 100)
  .lineTo(0, 100)
  .moveTo(10, 10)
  .lineTo(90, 10)
  .lineTo(90, 90)
  .lineTo(10, 90)
  .addHole();

v4.x 中的实例

¥Live example in v4.x

在 v5 中，图形得到了简化，API 从 addHole 更改为 beginHole 和 endHole。

¥In v5, Graphics has simplified and the API changed from addHole to beginHole and endHole.

const graphic = new PIXI.Graphics()
  .beginFill(0xff0000)
  .drawRect(0, 0, 100, 100)
  .beginHole()
  .drawCircle(50, 50, 30)
  .endHole();

开发中的实例

¥Live example in dev

过滤器填充​

¥Filter Padding

在 v4 中，过滤器的默认填充为 4，在 v5 中，这已更改为默认的 0。这可能会导致某些过滤器在使用时看起来破损。要解决此问题，只需向你创建的过滤器添加一些填充即可。

¥In v4 filters had a default padding of 4 and in v5 this has been changed to a default of 0. This can cause some filters to look broken when used. To fix this issue simply add some padding to the filters you create.

// Glow filter from https://github.com/pixijs/pixi-filters
const filter = new PIXI.filters.GlowFilter();
filter.padding = 4;

某些过滤器（例如 BlurFilter）会自动计算填充，因此可能不需要进行更改。

¥Some filters, like BlurFilter, automatically calculate the padding so changes may not be necessary.

过滤器默认顶点着色器​

¥Filter Default Vertex Shader

我们重新组织了所有专用于坐标系变换的制服，并重新命名了它们。如果你的过滤器不再起作用，请检查你是否使用默认顶点着色器。在这种情况下，你可以使用旧的 v4 顶点着色器代码。

¥We reorganized all uniforms dedicated to coordinate system transforms, and renamed them. If your filter doesn't work anymore, check if you use default vertex shader. In that case, you can use old v4 vertex shader code.

所有更改均在 [[Creating Filters|v5-Creating-filters]] 中进行了解释

¥All changes are explained in [[Creating Filters|v5-Creating-filters]]

为渲染纹理启用 Mipmapping​

¥Enable Mipmapping for RenderTexture

以前，你可能在 v4 中得到这样的代码（特别是如果你看到 伊万的评论/JSFiddle）：

¥Previously, you may have ended up with code like this in v4 (specifically if you saw Ivan's comment/JSFiddle):

const renderer = PIXI.autoDetectRenderer();
renderer.bindTexture(baseRenderTex, false, 0);
const glTex = baseRenderTex._glTextures[renderer.CONTEXT_UID];
glTex.enableMipmap(); // this is what actually generates mipmaps in WebGL
glTex.enableLinearScaling(); // this is what tells WebGL to USE those mipmaps

在 v5 中，不再需要此代码。

¥In v5, this code is no longer needed.

基础纹理资源​

¥BaseTexture Resources

v5 中的最新功能之一是我们将所有特定于资源的功能与 BaseTexture 解耦。我们创建了一个名为 "resources" 的新系统，每个 BaseTexture 现在都有一个封装某些特定资源类型的资源。例如：视频资源、SVG 资源、图片资源、Canvas 资源。未来，我们希望能够添加其他资源类型。如果之前调用过资源特定的方法或属性，这些方法或属性可能会在 baseTexture.resource 上。

¥One of the newest features in v5 is that we decoupled all the asset-specific functionality from BaseTexture. We created a new system called "resources" and each BaseTexture now has a resource that wraps some specific asset type. For instance: VideoResource, SVGResource, ImageResource, CanvasResource. In the future, we hope to be able to add other resource types. If there were asset-specific methods or properties being called before, these will probably be on baseTexture.resource.

此外，我们从 BaseTexture 中删除了所有 from* 方法，因此你只需调用 BaseTexture.from 并传入任何资源即可。有关 from 的更多信息，请参阅 docs。

¥Also, we removed all of the from* methods from BaseTexture, so you just can call BaseTexture.from and pass in whatever resource. Please see docs for more information about from.

const canvas = document.createElement('canvas');
const baseTexture = PIXI.BaseTexture.from(canvas);

该 API 还允许使用纯 WebGL 和 2d 上下文调用，请参阅 渐变示例。

¥That API also allows to use pure WebGL and 2d context calls, see the gradient example.

BaseTexture.source​

已移至 baseTexture.resource.source，移至 baseTexture 对应的资源中。RenderTexture 不存在 baseTexture.resource，对于没有源的资源，源也不存在。

¥Has been moved to baseTexture.resource.source, moved into resource corresponding to the baseTexture. baseTexture.resource does not exist for RenderTexture, and source does not exist for resources that dont have source.

图形交互​

¥Graphics Interaction

如果你使用透明交互式图形技巧，请确保为所有元素而不是其部分指定 alpha=0。PixiJS 如何处理 alpha=0 的形状被认为是未定义的行为。我们可能会将其改回来，但我们对此无法保证。

¥If you use transparent interactive graphics trick, make sure that you use specify alpha=0 for all element, not for its parts. How PixiJS deals with shapes that have alpha=0 is considered undefined behaviour. We might change it back, but we have no guarantees about it.

graphics.beginFill(0xffffff, 0.0); //bad
graphics.alpha = 0; //good

📦 发布变更​

¥📦 Publishing Changes

画布成为旧版​

¥Canvas Becomes Legacy

由于 WebGL 和 WebGL2 现在是一流的，因此我们已从默认的 pixi.js 包中删除了基于画布的后备。如果你需要 CanvasRenderer，你应该改用 pixi.js-legacy。

¥Since WebGL and WebGL2 are now first-class, we have removed the canvas-based fallback from the default pixi.js package. If you need CanvasRenderer, you should switch to use pixi.js-legacy instead.

import * as PIXI from "pixi.js";
// Will NOT return CanvasRenderer because canvas-based
// functionality was removed from "pixi.js"
const renderer = PIXI.autoDetectRenderer(); // return PIXI.Renderer or throws error

相反，使用旧包来访问画布渲染。

¥Instead, use the legacy bundle to have access to the canvas rendering.

import * as PIXI from "pixi.js-legacy";
const renderer = PIXI.autoDetectRenderer(); // returns PIXI.Renderer or PIXI.CanvasRenderer

打包更改​

¥Bundling Changes

如果你使用 Rollup、Parcel 或其他打包器将 PixiJS 添加到你的项目中，则在迁移到 v5 时会发生一些细微的变化。即，不再自动创建全局 PIXI 对象。出于两个目的，将其从打包中删除：1)

¥If you're using Rollup, Parcel or another bundler to add PixiJS into your project there are a few subtle changes when moving to v5. Namely, the global PIXI object is no longer created automatically. This was removed from bundling for two purpose: 1) to improve tree-shaking for bundlers, and 2) for security purpose by protecting PIXI.

这不再是有效的导入方式：

¥This is no longer a valid way to import:

import "pixi.js";
const renderer = PIXI.autoDetectRenderer(); // INVALID! No more global.PIXI!

相反，你应该导入为名称空间或单个元素：

¥Instead, you should import as a namespace or individual elements:

import * as PIXI from "pixi.js";
const renderer = PIXI.autoDetectRenderer();

// or even better:
import { autoDetectRenderer } from "pixi.js";
const renderer = autoDetectRenderer();

最后，一些第 3 方插件可能需要 window.PIXI，因此你可能必须像这样显式公开全局，但不建议这样做。

¥Lastly, some 3rd-party plugins maybe expecting window.PIXI, so you might have to explicitly expose the global like this, however this is not recommended.

import * as PIXI from 'pixi.js';
window.PIXI = PIXI; // some bundlers might prefer "global" instead of "window"

Webpack​

当使用 Webpack 和第 3 方插件（例如 pixi-spine）时，你可能会在构建全局 PIXI 对象时遇到困难，从而导致运行时错误 ReferenceError: PIXI is not defined。通常可以使用 Webpack 调整全局变量 来解决。

¥When Webpack and 3rd-party plugins, like pixi-spine, you might have difficulties building the global PIXI object resulting in a runtime error ReferenceError: PIXI is not defined. Usually this can be resolved by using Webpack shimming globals.

例如，这是你的导入代码：

¥For instance, here's your import code:

import * as PIXI from 'pixi.js';
import 'pixi-spine'; // or other plugins that need global 'PIXI' to be defined first

在 webpack.config.js 中添加 plugins 部分，让 Webpack 知道全局 PIXI 变量引用了 pixi.js 模块。例如：

¥Add a plugins section to your webpack.config.js to let know Webpack that the global PIXI variable make reference to pixi.js module. For instance:

const webpack = require('webpack');

module.exports = {
    entry: '...',
    output: {
        ...
    },
    plugins: [
     new webpack.ProvidePlugin({
       PIXI: 'pixi.js'
     })
   ]
}