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）。

¥Container is the base class for all scene objects in v8 (replacing the old DisplayObject).

  • 可以包含子元素。

    ¥Can have children.

  • 通常用于对对象进行分组并对组应用变换（位置、缩放、旋转）。

    ¥Commonly used to group objects and apply transformations (position, scale, rotation) to the group.

  • 示例：Application.stage，用户定义的组。

    ¥Examples: Application.stage, user-defined groups.

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 中无效）：

¥Before v8 (invalid in v8):

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

v8 方法：

¥v8 approach:

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

变换​

¥Transforms

PixiJS 中的所有场景对象都具有多个属性，用于控制其位置、旋转、缩放和 Alpha 值。这些属性由子对象继承，允许你轻松地将变换应用于对象组。

¥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.

属性描述
positionX 和 Y 位置以像素为单位给出，并更改对象相对于其父对象的位置，也可以直接用作 object.x / object.y
rotation旋转以弧度指定，并顺时针旋转对象 (0.0 - 2 * Math.PI)
angle角度是旋转的别名，以度而不是弧度指定 (0.0 - 360.0)
pivot对象旋转的点（以像素为单位） - 还设置子对象的原点
alpha不透明度从 0.0（完全透明）到 1.0（完全不透明），由子级继承
scale比例指定为百分比，1.0 为 100% 或实际大小，并且可以为 x 和 y 轴独立设置
skewSkew 与 CSS skew() 函数类似，在 x 和 y 方向上变换对象，并以弧度指定
锚点？锚点是基于百分比的精灵位置和旋转偏移量。这与 pivot 属性不同，后者是基于像素的偏移量。

锚点 vs Pivot​

¥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.

信息

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

¥Setting either pivot or anchor visually moves the node. This differs from CSS where changing transform-origin does not affect the element's position.

锚点​

¥Anchor

  • 仅适用于 Sprite

    ¥Available only on Sprite

  • 以规范化值 (0.0 to 1.0) 定义

    ¥Defined in normalized values (0.0 to 1.0)

  • (0, 0) 位于左上角，(0.5, 0.5) 位于中心

    ¥(0, 0) is the top-left, (0.5, 0.5) is the center

  • 更改位置和旋转原点

    ¥Changes both position and rotation origin

sprite.anchor.set(0.5); // center
sprite.rotation = Math.PI / 4; // Rotate 45 degrees around the center

枢轴​

¥Pivot

  • 适用于所有 Container

    ¥Available on all Containers

  • 以像素定义，未经规范化

    ¥Defined in pixels, not normalized

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()。

    ¥Local bounds represent the object’s dimensions in its own coordinate space. Use getLocalBounds().

  • 全局边界表示对象在世界坐标系中的边界框。使用 getBounds()。

    ¥Global bounds represent the object's bounding box in world coordinates. Use 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 对象定义形状。

    ¥Graphics-based masks: Use a Graphics object to define the shape.

  • 基于精灵的遮罩：使用 Sprite 或其他可渲染对象。

    ¥Sprite-based masks: Use a Sprite or other renderable object.

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

  • 蒙版不会被渲染；它仅用于定义可见区域。但是，必须将其添加到显示列表中。

    ¥The mask is not rendered; it's used only to define the visible area. However, it must be added to the display list.

  • 每个对象只能分配一个遮罩。

    ¥Only one mask can be assigned per object.

  • 对于高级混合，请使用 Alpha 蒙版或滤镜（将在后续指南中介绍）。

    ¥For advanced blending, use alpha masks or filters (covered in later guides).

过滤器​

¥Filters

容器对象的另一个常见用途是作为过滤内容的宿主。滤镜是一项仅限 WebGL/WebGPU 的高级功能，允许 PixiJS 执行每像素效果，例如模糊和位移。通过在容器上设置过滤器，容器所包含的屏幕区域将在渲染容器的内容后由过滤器处理。

¥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);
信息

应谨慎使用过滤器。如果在场景中使用过于频繁，它们会降低性能并增加内存使用量。

¥Filters should be used somewhat sparingly. They can slow performance and increase memory usage if used too often in a scene.

以下是 PixiJS 中默认可用的过滤器列表。然而，有一个带有 更多过滤器 的社区存储库。

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

筛选描述
AlphaFilter与设置 alpha 属性类似，但展平 Container 而不是单独应用于子项。
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，否则 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：默认混合模式。

    ¥normal: Default blend mode.

  • add：添加源像素和目标像素的颜色。

    ¥add: Adds the colors of the source and destination pixels.

  • multiply：将源像素和目标像素的颜色相乘。

    ¥multiply: Multiplies the colors of the source and destination pixels.

  • screen：反转颜色，相乘，然后再次反转。

    ¥screen: Inverts the colors, multiplies them, and inverts again.

我们还支持更多高级混合模式，例如 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