Skip to main content

场景对象

🌐 Scene Objects

在 PixiJS 中，场景对象是应用显示层次结构的构建模块。它们包括 容器、精灵、文本、图形 以及其他可绘制的实体，这些实体构成了 场景图——一种树状结构，用于决定哪些内容被渲染、如何渲染以及渲染的顺序。

🌐 In PixiJS, scene objects are the building blocks of your application’s display hierarchy. They include containers, sprites, text, graphics, and other drawable entities that make up the scene graph—the tree-like structure that determines what gets rendered, how, and in what order.

容器 vs. 叶节点​

🌐 Containers vs. Leaf Nodes

PixiJS 中的场景对象可以分为 容器 和 叶节点：

🌐 Scene objects in PixiJS can be divided into containers and leaf nodes:

容器​

🌐 Containers

Container 是 v8 中所有场景对象的 基类（取代了旧的 DisplayObject）。

  • 可以包含子元素。
  • 通常用于对对象进行分组并对组应用变换（位置、缩放、旋转）。
  • 示例：Application.stage，用户定义的组。
const group = new Container();
group.addChild(spriteA);
group.addChild(spriteB);

叶节点​

🌐 Leaf Nodes

叶节点是可渲染对象，不应有子节点。在 v8 中，只有容器才应有子节点。

🌐 Leaf nodes are renderable objects that should not have children. In v8, only containers should have children.

叶节点示例包括：

🌐 Examples of leaf nodes include:

  • Sprite
  • Text
  • Graphics
  • Mesh
  • TilingSprite
  • HTMLText

尝试向叶节点添加子节点不会导致运行时错误，然而，你可能会遇到意外的渲染行为。因此，如果需要嵌套，请将叶节点封装在 Container 中。

🌐 Attempting to add children to a leaf node will not result in a runtime error, however, you may run into unexpected rendering behavior. Therefore, If nesting is required, wrap leaf nodes in a Container.

在 v8 之前（v8 中无效）：

const sprite = new Sprite();
sprite.addChild(anotherSprite); // ❌ Invalid in v8

v8 方法：

const group = new Container();
group.addChild(sprite);
group.addChild(anotherSprite); // ✅ Valid

变换​

🌐 Transforms

PixiJS 中的所有场景对象都有若干属性，用于控制它们的位置、旋转、缩放和透明度。这些属性会被子对象继承，使你能够轻松地对对象组应用变换。

🌐 All scene objects in PixiJS have several properties that control their position, rotation, scale, and alpha. These properties are inherited by child objects, allowing you to apply transformations to groups of objects easily.

你经常会使用这些属性来定位和动画场景中的对象。

🌐 You will often use these properties to position and animate objects in your scene.

属性描述
位置X 和 Y 位置以像素为单位，改变对象相对于其父对象的位置，也可以直接作为 object.x / object.y 使用
旋转旋转以弧度表示，使对象顺时针旋转（0.0 - 2 * Math.PI）
角度角度是旋转的别名，以度数而不是弧度指定（0.0 - 360.0）
枢轴对象旋转的中心点，以像素为单位 - 也设置子对象的原点
alpha不透明度，从 0.0（完全透明）到 1.0（完全不透明），会被子元素继承
缩放缩放以百分比指定，1.0 为 100% 或实际大小，并且可以独立设置 x 轴和 y 轴
倾斜倾斜在 x 和 y 方向上变换对象，类似于 CSS 的 skew() 函数，并以弧度为单位指定
锚点？锚点是基于百分比的精灵位置和旋转偏移。这与 pivot 属性不同，pivot 是基于像素的偏移。

锚点 vs 枢轴​

🌐 Anchor vs Pivot

一些叶节点有一个额外的属性，称为 anchor，它是基于百分比的节点位置和旋转偏移。这不同于 pivot 属性，它是基于像素的偏移。在定位或旋转节点时，理解锚点和枢轴点之间的区别至关重要。

🌐 Some leaf nodes have an additional property called anchor, which is a percentage-based offset for the nodes position and rotation. This is different from the pivot property, which is a pixel-based offset. Understanding the difference between anchor and pivot is critical when positioning or rotating a node.

info

设置枢轴或锚点会在视觉上移动节点。这与 CSS 不同，在 CSS 中更改 transform-origin 不会影响元素的位置。

锚​

🌐 Anchor

  • 仅在 Sprite 可用
  • 在归一化值 (0.0 to 1.0) 中定义
  • (0, 0) 是左上角，(0.5, 0.5) 是中心
  • 更改位置和旋转原点
sprite.anchor.set(0.5); // center
sprite.rotation = Math.PI / 4; // Rotate 45 degrees around the center

枢轴​

🌐 Pivot

  • 适用于所有 Container
  • 以像素定义，而非归一化
const sprite = new Sprite(texture);
sprite.width = 100;
sprite.height = 100;
sprite.pivot.set(50, 50); // Center of the container
container.rotation = Math.PI / 4; // Rotate 45 degrees around the pivot

测量边界​

🌐 Measuring Bounds

PixiJS 中有两种类型的边界：

🌐 There are two types of bounds in PixiJS:

  • 局部边界表示对象在其自身坐标空间中的尺寸。使用 getLocalBounds()。
  • 全局边界表示对象在世界坐标中的边界框。使用 getBounds()。
const local = container.getLocalBounds();
const global = container.getBounds();

如果性能至关重要，你也可以提供自定义的 boundsArea 来完全避免对每个子元素的测量。

🌐 If performance is critical you can also provide a custom boundsArea to avoid per-child measurement entirely.

更改大小​

🌐 Changing size

要更改容器的大小，你可以使用 width 和 height 属性。这将按指定的尺寸调整容器的大小：

🌐 To change the size of a container, you can use the width and height properties. This will scale the container to fit the specified dimensions:

const container = new Container();
container.width = 100;
container.height = 200;

单独设置 width 和 height 可能是一个代价高的操作，因为它需要重新计算容器及其子元素的边界。为了避免这种情况，你可以使用 setSize() 一次性设置两个属性：

🌐 Setting the width and height individually can be an expensive operation, as it requires recalculating the bounds of the container and its children. To avoid this, you can use setSize() to set both properties at once:

const container = new Container();
container.setSize(100, 200);
const size = container.getSize(); // { width: 100, height: 200 }

这种方法比单独设置 width 和 height 更高效，因为它只需要一次边界计算。

🌐 This method is more efficient than setting width and height separately, as it only requires one bounds calculation.

遮罩场景对象​

🌐 Masking Scene Objects

PixiJS 支持 遮罩，允许你根据另一个对象的形状限制场景对象的可见区域。这对于创建裁剪、显示或隐藏场景部分的效果非常有用。

🌐 PixiJS supports masking, allowing you to restrict the visible area of a scene object based on another object's shape. This is useful for creating effects like cropping, revealing, or hiding parts of your scene.

遮罩类型​

🌐 Types of Masks

  • 基于图形的蒙版：使用 Graphics 对象来定义形状。
  • 基于精灵的遮罩：使用 Sprite 或其他可渲染对象。
const shape = new Graphics().circle(100, 100, 50).fill(0x000000);

const maskedSprite = new Sprite(texture);
maskedSprite.mask = shape;

stage.addChild(shape);
stage.addChild(maskedSprite);

反向蒙版​

🌐 Inverse Masks

要创建反向蒙版，你可以使用 setMask 属性并将其 inverse 选项设置为 true。这将渲染蒙版外的所有内容。

🌐 To create an inverse mask, you can use the setMask property and set its inverse option to true. This will render everything outside the mask.

const inverseMask = new Graphics().rect(0, 0, 200, 200).fill(0x000000);
const maskedContainer = new Container();
maskedContainer.setMask({ mask: inverseMask, inverse: true });
maskedContainer.addChild(sprite);
stage.addChild(inverseMask);
stage.addChild(maskedContainer);

遮罩说明​

🌐 Notes on Masking

  • 这个遮罩不会被渲染；它仅用于定义可见区域。不过，它必须被添加到显示列表中。
  • 每个对象只能分配一个遮罩。
  • 对于高级混合，使用Alpha蒙版或滤镜（将在后续指南中介绍）。

过滤器​

🌐 Filters

Container 对象的另一个常见用途是作为过滤内容的容器。过滤器是一个高级的、仅适用于 WebGL/WebGPU 的功能，它允许 PixiJS 执行逐像素效果，如模糊和位移。通过在 Container 上设置过滤器，Container 所包含的屏幕区域将在 Container 的内容渲染完成后被过滤器处理。

🌐 Another common use for Container objects is as hosts for filtered content. Filters are an advanced, WebGL/WebGPU-only feature that allows PixiJS to perform per-pixel effects like blurring and displacements. By setting a filter on a Container, the area of the screen the Container encompasses will be processed by the filter after the Container's contents have been rendered.

const container = new Container();
const sprite = new Sprite(texture);
const filter = new BlurFilter({ strength: 8, quality: 4, kernelSize: 5 });
container.filters = [filter];
container.addChild(sprite);
info

滤镜应该适度使用。如果在场景中使用太频繁，它们会降低性能并增加内存使用。

以下是 PixiJS 默认提供的滤镜列表。不过，也有一个社区仓库提供了更多滤镜。

🌐 Below are list of filters available by default in PixiJS. There is, however, a community repository with many more filters.

滤镜描述
AlphaFilter类似于设置 alpha 属性，但将容器平铺，而不是单独应用于子项。
BlurFilter应用模糊效果
ColorMatrixFilter颜色矩阵是一种灵活的方法，用于应用更复杂的染色或颜色转换（例如，褐褐色效果）。
DisplacementFilter位移图创建视觉偏移像素，例如创建波浪水面效果。
NoiseFilter创建随机噪点（例如，颗粒效果）。

在底层，我们提供的每个滤镜都是用 glsl（用于 WebGL）和 wgsl（用于 WebGPU）编写的。这意味着所有滤镜都应该在两种渲染器上工作。

🌐 Under the hood, each Filter we offer out of the box is written in both glsl (for WebGL) and wgsl (for WebGPU). This means all filters should work on both renderers.

着色​

🌐 Tinting

你可以通过设置 tint 属性来给任何场景对象上色。它会修改渲染像素的颜色，类似于在对象上乘以一个色彩滤镜。

🌐 You can tint any scene object by setting the tint property. It modifies the color of the rendered pixels, similar to multiplying a tint color over the object.

const sprite = new Sprite(texture);
sprite.tint = 0xff0000; // Red tint
sprite.tint = 'red'; // Red tint

tint 会被子对象继承，除非它们指定了自己的。如果只希望场景的一部分被着色，请将它放在一个单独的容器中。

🌐 The tint is inherited by child objects unless they specify their own. If only part of your scene should be tinted, place it in a separate container.

0xFFFFFF 的值会禁用着色。

🌐 A value of 0xFFFFFF disables tinting.

const sprite = new Sprite(texture);
sprite.tint = 0x00ff00; // Green tint
sprite.tint = 0xffffff; // No tint

PixiJS 支持多种颜色格式，你可以从 颜色文档 获取更多信息。

🌐 PixiJS supports a variety of color formats and you can find more information from the Color documentation.

混合模式​

🌐 Blend Modes

混合模式决定了重叠对象的颜色如何组合。PixiJS 支持多种混合模式，包括：

🌐 Blend modes determine how colors of overlapping objects are combined. PixiJS supports a variety of blend modes, including:

  • normal：默认混合模式。
  • add：添加源像素和目标像素的颜色。
  • multiply：将源像素和目标像素的颜色相乘。
  • screen：反转颜色，相乘，然后再次反转。

我们还支持更多高级的混合模式，例如 subtract、difference 和 overlay。你可以在 混合模式文档 中找到完整的混合模式列表。

🌐 We also support may more advanced blend modes, such as subtract, difference, and overlay. You can find the full list of blend modes in the Blend Modes documentation.

const sprite = new Sprite(texture);
sprite.blendMode = 'multiply'; // Multiply blend mode

互动​

🌐 Interaction

PixiJS 提供了一个强大的交互系统，允许你处理用户输入事件，比如点击/悬停。要在场景对象上启用交互，可以简单地将其 interactive 属性设置为 true。

🌐 PixiJS provides a powerful interaction system that allows you to handle user input events like clicks/hovers. To enable interaction on a scene object, can be as simple as setting its interactive property to true.

const sprite = new Sprite(texture);
sprite.interactive = true;
sprite.on('click', (event) => {
  console.log('Sprite clicked!', event);
});

我们有一份关于 交互 的详细指南，涵盖了如何设置和管理交互，包括命中测试、指针事件等。我们强烈建议查看该指南。

🌐 We have a detailed guide on Interaction that covers how to set up and manage interactions, including hit testing, pointer events, and more. We highly recommend checking it out.

使用 onRender​

🌐 Using onRender

onRender 回调允许你在每一帧场景对象渲染时执行逻辑。这对于轻量级动画和更新逻辑非常有用：

🌐 The onRender callback allows you to run logic every frame when a scene object is rendered. This is useful for lightweight animation and update logic:

const container = new Container();
container.onRender = () => {
  container.rotation += 0.01;
};

注意：在 PixiJS v8 中，这取代了常见的 v7 模式，即覆盖 updateTransform，该模式不再每帧运行。onRender 函数会注册到容器所属的渲染组。

🌐 Note: In PixiJS v8, this replaces the common v7 pattern of overriding updateTransform, which no longer runs every frame. The onRender function is registered with the render group the container belongs to.

要删除回调：

🌐 To remove the callback:

container.onRender = null;

API 参考​

🌐 API Reference