应用

🌐 Application

Application 类提供了一个现代化的、可扩展的入口点来在 PixiJS 中设置渲染。它抽象了渲染器设置和计时器更新等常见任务，并且设计为通过异步初始化支持 WebGL 和 WebGPU。

🌐 The Application class provides a modern, extensible entry point to set up rendering in PixiJS. It abstracts common tasks like renderer setup and ticker updates, and is designed to support both WebGL and WebGPU via async initialization.

创建应用

🌐 Creating an Application

创建一个应用需要两个步骤：构建一个实例，然后使用 .init() 异步初始化它：

🌐 Creating an application requires two steps: constructing an instance, then initializing it asynchronously using .init():

import { Application } from 'pixi.js';

const app = new Application();

await app.init({
  width: 800,
  height: 600,
  backgroundColor: 0x1099bb,
});

document.body.appendChild(app.canvas);

应用选项参考

🌐 ApplicationOptions Reference

Application 的 .init() 方法接收一个具有以下配置选项的 Partial<ApplicationOptions> 对象：

🌐 The .init() method of Application accepts a Partial<ApplicationOptions> object with the following configuration options:

选项	类型	默认值	描述
`autoStart`	`boolean`	`true`	是否在初始化后立即开始渲染。设置为 `false` 不会停止已在运行的共享计时器。
`resizeTo`	`Window \| HTMLElement`	—	用于自动调整渲染器大小以匹配的元素。
`sharedTicker`	`boolean`	`false`	如果 `true`，使用共享的计时器实例；否则，将创建一个私有计时器。
`preference`	`'webgl' \| 'webgpu'`	`webgl`	首选渲染器类型。
`useBackBuffer`	`boolean`	`false`	(仅限 WebGL) 在需要时使用后台缓冲。
`forceFallbackAdapter`	`boolean`	`false`	(仅限 WebGPU) 强制使用备用适配器。
`powerPreference`	`'high-performance' \| 'low-power'`	`undefined`	GPU 性能偏好提示（WebGL 和 WebGPU）。
`antialias`	`boolean`	—	启用抗锯齿。可能会影响性能。
`autoDensity`	`boolean`	—	根据 `resolution` 调整画布大小。仅适用于 `HTMLCanvasElement`。
`background`	`ColorSource`	—	`backgroundColor` 的别名。
`backgroundAlpha`	`number`	`1`	背景的透明度（0 = 透明，1 = 不透明）。
`backgroundColor`	`ColorSource`	`'black'`	用于清空画布的颜色。接受十六进制、CSS颜色或数组。
`canvas`	`ICanvas`	—	自定义画布实例（可选）。
`clearBeforeRender`	`boolean`	`true`	渲染器是否应在每帧清除画布。
`context`	`WebGL2RenderingContext \| null`	`null`	用户提供的渲染上下文（WebGL）。
`depth`	`boolean`	—	在主视图中启用深度缓冲区。对于 WebGL 始终 `true`。
`height`	`number`	`600`	渲染器的初始高度（以像素为单位）。
`width`	`number`	`800`	渲染器的初始宽度（以像素为单位）。
`hello`	`boolean`	`false`	将渲染器信息和版本记录到控制台。
`multiView`	`boolean`	`false`	启用多画布渲染。
`preferWebGLVersion`	`1 \| 2`	`2`	首选的 WebGL 版本。
`premultipliedAlpha`	`boolean`	`true`	假设颜色缓冲区中的 alpha 已经预乘。
`preserveDrawingBuffer`	`boolean`	`false`	保留帧之间的缓冲区。`toDataURL` 需要它。
`resolution`	`number`	1	渲染器的分辨率。
`skipExtensionImports`	`boolean`	`false`	防止自动导入默认的 PixiJS 扩展。
`textureGCActive`	`boolean`	`true`	启用 GPU 纹理的垃圾回收。
`textureGCCheckCountMax`	`number`	`600`	GC 运行之间的帧间隔（纹理）。
`textureGCMaxIdle`	`number`	`3600`	在销毁纹理之前的最大空闲帧数。
`textureGCAMaxIdle`	`number`	—	（看起来未记录；用于内部 GC 控制的占位符。）

根据渲染器类型自定义应用选项

🌐 Customizing Application Options Per Renderer Type

你也可以通过使用 WebGLOptions 或 WebGPUOptions 接口，根据渲染器类型覆盖属性。例如：

🌐 You can also override properties based on the renderer type by using the WebGLOptions or WebGPUOptions interfaces. For example:

import { Application } from 'pixi.js';

const app = new Application();
await app.init({
  width: 800,
  height: 600,
  backgroundColor: 0x1099bb,
  webgl: {
    antialias: true,
  },
  webgpu: {
    antialias: false,
  },
});
document.body.appendChild(app.canvas);

内置插件

🌐 Built-In Plugins

PixiJS 包含：

🌐 PixiJS includes:

✅ Ticker 插件 — 每帧更新 → 指南
✅ 调整大小插件 — 调整渲染器/画布尺寸 → 指南
➕ 可选：Culler 插件 - 剔除画面外的对象 → 指南

创建自定义应用插件

🌐 Creating a Custom Application Plugin

你可以为 Application 类创建自定义插件。插件必须实现 ApplicationPlugin 接口，该接口包含 init() 和 destroy() 方法。你还可以指定 extension 类型，对于应用插件，该类型为 ExtensionType.Application。

🌐 You can create custom plugins for the Application class. A plugin must implement the ApplicationPlugin interface, which includes init() and destroy() methods. You can also specify the extension type, which is ExtensionType.Application for application plugins.

两个函数都在将 this 设置为 Application 实例时调用，例如 this.renderer 或 this.stage 可用。

🌐 Both functions are called with this set as the Application instance e.g this.renderer or this.stage is available.

init() 方法在应用初始化时被调用，并传递来自 application.init 调用的选项，而 destroy() 方法在应用被销毁时被调用。

🌐 The init() method is called when the application is initialized and passes the options from the application.init call, and the destroy() method is called when the application is destroyed.

import type { ApplicationOptions, ApplicationPlugin, ExtensionType } from 'pixi.js';

const myPlugin: ApplicationPlugin = {
    extension: ExtensionType.Application;
    init(options: ApplicationOptions) {
        console.log('Custom plugin init:', this, options);
    },
    destroy() {
        console.log('Custom plugin destroy');
    },
};

🌐 Register with:

import { extensions } from 'pixi.js';
extensions.add(myPlugin);

添加类型

🌐 Adding Types

如果你正在使用 TypeScript，或者正在为他人提供插件，你可以扩展 ApplicationOptions 接口以包含你自定义的插件选项。

🌐 If you are using TypeScript, or are providing a plugin for others to use, you can extend the ApplicationOptions interface to include your custom plugins options.

declare global {
  namespace PixiMixins {
    interface ApplicationOptions {
      myPlugin?: import('./myPlugin').PluginOptions | null;
    }
  }
}

await app.init({
  myPlugin: {
    customOption: true, // Now TypeScript will know about this option
  },
});

API 参考

🌐 API Reference

创建应用​

应用选项参考​

根据渲染器类型自定义应用选项​

内置插件​

创建自定义应用插件​

添加类型​

API 参考​