版本：v8.x

v5 遷移指南

此文件適用於嘗試從 v4 升級至 v5 的開發人員。本指南包含陷阱與重要背景資訊，幫助您瞭解 v4 程式碼需要微妙變更的原因。我們一般會盡量在 v5 中採用反向相容性機制，搭配在 console 中發出過期警告。不過，有時變更太過重大了，需要一些額外的協助。

🚧 API 變更

讓 WebGL 成為優先

PixiJS v5 已將 WebGL 設為優先渲染器，而將 CanvasRenderer 設為次要渲染器。從功能上來說，v4 與 v5 並沒有太大的不同，但是有一些細微的內部命名變更可能會讓升級至 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

注意：在渲染器或應用程式建構函式選項中加入 transparent: true 可能有助於修正某些裝置上出現的奇怪圖形，但它可能會降低 FPS。這比 preserveDrawingBuffer: true 還要好。
如果你需要使用 v4 的預設行為來調整畫布大小使用 css 像素，請將 autoDensity: true 加入選項中。

並非所有內容都轉換為 params。即使 WebGL2 可用，若要啟用 WebGL1，請使用

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

網格、平面、繩索

PixiJS v5 引入一個稱為 PIXI.Mesh 的新類別。這讓你可以覆寫預設著色器，並增加更多屬性到幾何體中。對於範例，你可以將顏色加入頂點。

舊 v4 網格類別已從 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 屬性緩衝中。例如，這是如何存取透過 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，會自動計算邊距，因此可能不需要變更。

套用濾鏡預設頂點著色器

我們重新組織專用於座標系變換的所有 uniforms，並重新命名它們。如果你的套用濾鏡不再運作，請檢查你是否使用預設頂點著色器。如果是，你可以使用舊的 v4 頂點著色器程式碼。

所有變更說明都記載在 [[建立套用濾鏡|v5-建立套用濾鏡]]

為 RenderTexture 啟用 MIP 映射

先前，您可能在 v4 (特別是您看到 Ivan 的留言/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 中，此代碼不再需要。

基本材質資源

v5 中最新功能之一是，我們將所有特定於資產的功能從基本材質中分離出來。我們建立了一個稱為「資源」的新系統，現在每個基本材質都有資源，該資源包裝一些特定資產類型。例如：VideoResource、SVGResource、ImageResource、CanvasResource。未來，我們希望能夠新增其他資源類型。如果先前已呼叫特定於資產的方法或屬性，這些內容可能在 baseTexture.resource 上。

此外，我們從基本材質中移除了所有 from* 方法，所以您只要呼叫 BaseTexture.from，然後傳入任何資源即可。有關 from 的詳細資訊，請參閱文件。

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

該 API 也允許使用純 WebGL 和 2d 內容呼叫，請參閱漸層範例。

基本材質.source

已移至 baseTexture.resource.source，移至對應於基本材質的資源中。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) 改善套件整理的 tree-shaking，以及 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 is not defined。通常這可以使用Webpack 偽造全局來解決。

例如，以下是您的匯入程式碼

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

在你的webpack.config.js中加入一個plugin區塊，以讓 Webpack 知道全局PIXI變數指的是pixi.js模組。例如

const webpack = require('webpack');

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

v5 遷移指南

🚧 API 變更​

讓 WebGL 成為優先​

渲染器參數​

網格、平面、繩索​

圖形洞​

套用濾鏡邊距​

套用濾鏡預設頂點著色器​

為 RenderTexture 啟用 MIP 映射​

基本材質資源​

基本材質.source​

圖形互動​

📦 發佈變更​

畫布成為舊版​

套件變更​

Webpack​