v5 迁移指南

此文档对尝试从v4 升级到 v5的开发者很有用。其中包括疑难解答、以及了解为什么你的 v4 代码可能需要进行一些微调的重要背景信息。总的来说，我们尝试尽可能地向后兼容 v5，并使用控制台中的弃用警告。然而，有时当修改过于重大的时候，需要一些额外帮助。

🚧 API 变更

使 WebGL 成为首选

PixiJS v5 已将 WebGL 设置为首选渲染器，而 CanvasRenderer 则变为次要渲染器。从功能上讲，v4 没有什么变化，但存在一些微妙的内部命名更改，可能会给升级到 v5 的某些开发者带来麻烦。例如

• WebGLRenderer 变为 Renderer
• renderWebGL 变为 render（在 DisplayObject、Sprite、Container 等中）
• _renderWebGL 变为 _render（在 DisplayObject、Container 等中）

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

渲染器参数

在 Renderer 构造函数中将 options 指定为第三个参数已被正式弃用（PIXI.Application、PIXI.autoDetectRenderer 和 PIXI.CanvasRenderer 也一样）。在 v4 中，我们支持两个函数签名，但在 v5 中，我们去掉了 width, height, options 签名。请将 width 和 height 添加到 options。

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

• 注意：在 Renderer 或 Application 构造函数选项中添加 transparent: true 可能会解决某些设备上的奇怪伪像，但它可能会降低 FPS。它比 preserveDrawingBuffer: true 要好得多。

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

并非一切都转到了参数中。要启用 WebGL1（即使 WebGL2 可用），请使用

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

网格、平面、绳索

PixiJS v5 引入了新类，称为 PIXI.Mesh。这允许覆盖默认着色器，并能够向几何图形中添加更多属性。对于 示例，你可以为顶点添加颜色。

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

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

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

PIXI.SimpleMesh 字段 vertices、uvs、indices 被包装在 mesh.geometry 属性 buffers 中。例如，这是如何通过 mesh.uvBuffer 属性访问缓冲区

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

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

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

图形孔洞

在 v4 中图形中的绘图孔洞非常有限。这仅支持非形状绘图，比如使用 lineTo、bezierCurveTo 等。在 v5 中，我们通过支持形状改进了孔洞 API。不幸的是，没有弃用策略来支持 v4 API。例如，在 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 中的实时示例

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

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

dev 中的实时示例

滤镜填充

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

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

一些滤镜，如 BlurFilter，会自动计算填充，因此可能不需要更改。

滤镜默认顶点着色器

我们重新组织了所有专用于坐标系转换的统一变量，并对其进行了重命名。如果你的滤镜不再工作，请检查你是否使用了默认顶点着色器。如果是这种情况，你可以使用旧 v4 顶点着色器代码。

所有更改均已在此处说明： [[创建滤镜|v5-创建滤镜]]

为 RenderTexture 启用 Mipmapping

auparavant，你可能最终会在 v4 中得到如以下类似的代码（如果你看到 伊万的评论/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 中，不再需要此代码。

BaseTexture 资源

v5 中最新的功能之一是，我们解除了 BaseTexture 中所有针对特定资源的功能。我们创建了一个名为“资源”的新系统，每个 BaseTexture 现在都有一个包装某些特定资源类型的资源。例如：VideoResource、SVGResource、ImageResource、CanvasResource。将来，我们希望能够添加其他资源类型。如果之前调用过针对特定资源的方法或属性，那么这些方法或属性可能会在 baseTexture.resource 中。

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

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

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

BaseTexture.source

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

图形交互

如果你使用了透明互动式图形技巧，请确保对元素指定 alpha=0，而不是其组件。PixiJS 对 alpha=0 的形状的处理方式被视为未定义行为。我们可以在将来改回来，但对此没有任何保证。

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

📦 发布更改

画布成为旧版

由于 WebGL 和 WebGL2 现在是一流的，我们已经默认的 pixi.js 软件包中移除了基于画布的备用机制。如果你需要 CanvasRenderer，你应该改用 pixi.js-legacy。

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

相反，使用旧版捆绑包以获得对画布渲染的访问权限。

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

捆绑更改

如果你使用 Rollup、Parcel 或其他捆绑器将 PixiJS 添加到项目中，在迁移到 v5 时会出现一些微妙的更改。也就是说，全局 PIXI 对象不再自动创建。这样做有两个目的：1）为捆绑器提高树摇晃功能，2）通过保护 PIXI 来达到安全目的。

这不再是有效的导入方式

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

相反，你应该导入命名空间或各个元素

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

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

最后，一些第三方插件可能期望 window.PIXI，因此你可能必须像这样明确显示全局变量，但不推荐这样做。

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

Webpack

当使用 Webpack 和第三方插件（如 pixi-spine）时，你可能难以构建全局 PIXI 对象，从而导致运行时错误 ReferenceError: 未定义 PIXI。通常，可以通过使用 Webpack 模块垫片全局变量 来解决此问题。

例如，这是你的导入代码

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 模块。例如

const webpack = require('webpack');

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