容器

¥Containers

容器 类提供了一个简单的显示对象，其功能正如其名称所暗示的那样 - 将一组子对象收集在一起。但除了对对象进行分组之外，容器还有一些你应该注意的用途。

¥The Container class provides a simple display object that does what its name implies - collect a set of child objects together. But beyond grouping objects, containers have a few uses that you should be aware of.

常用属性

¥Commonly Used Attributes

在 PixiJS 中对内容进行布局和动画处理时最常用的属性由 Container 类提供：

¥The most common attributes you'll use when laying out and animating content in PixiJS are provided by the Container class:

属性	描述
position	X 和 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 轴独立设置
skew	Skew 与 CSS skew() 函数类似，在 x 和 y 方向上变换对象，并以弧度指定
visible	对象是否可见，作为布尔值 - 防止更新和渲染对象和子对象
renderable	是否应该渲染对象 - 当 false 时，对象仍然会更新，但不会渲染，不影响子对象

容器作为组

¥Containers as Groups

几乎每一种类型的显示对象也都源自 Container！这意味着在许多情况下，你可以使用要渲染的对象创建父子层次结构。

¥Almost every type of display object is also derived from Container! This means that in many cases you can create a parent-child hierarchy with the objects you want to render.

但是，最好不要这样做。独立 Container 对象的渲染成本非常低，并且具有适当的 Container 对象层次结构（每个容器对象都包含一个或多个可渲染对象），为渲染顺序提供了灵活性。它还可以保证你的代码面向未来，因为当你需要向树的分支添加额外的对象时，你的动画逻辑不需要更改 - 只需将新对象放入适当的容器中，你的逻辑就会移动容器，而无需更改代码。

¥However, it's a good idea not to do this. Standalone Container objects are very cheap to render, and having a proper hierarchy of Container objects, each containing one or more renderable objects, provides flexibility in rendering order. It also future-proofs your code, as when you need to add an additional object to a branch of the tree, your animation logic doesn't need to change - just drop the new object into the proper Container, and your logic moves the Container with no changes to your code.

这就是容器的主要用途 - 作为层次结构中的可渲染对象组。

¥So that's the primary use for Containers - as groups of renderable objects in a hierarchy.

看看 容器示例代码。

¥Check out the container example code.

掩蔽

¥Masking

容器对象的另一个常见用途是作为屏蔽内容的宿主。"掩蔽" 是一种技术，场景图的部分内容仅在给定区域内可见。

¥Another common use for Container objects is as hosts for masked content. "Masking" is a technique where parts of your scene graph are only visible within a given area.

想象一个弹出窗口。它有一个由一个或多个精灵组成的框架，然后有一个可滚动的内容区域，隐藏框架之外的内容。容器加上遮罩使可滚动区域易于实现。添加 Container，将其 mask 属性设置为带有矩形的 Graphics 对象，然后添加要显示为该屏蔽 Container 子级的文本、图片等内容。任何超出矩形遮罩的内容都不会被绘制。移动容器的内容以根据需要滚动。

¥Think of a pop-up window. It has a frame made of one or more Sprites, then has a scrollable content area that hides content outside the frame. A Container plus a mask makes that scrollable area easy to implement. Add the Container, set its mask property to a Graphics object with a rect, and add the text, image, etc. content you want to display as children of that masked Container. Any content that extends beyond the rectangular mask will simply not be drawn. Move the contents of the Container to scroll as desired.

// Create the application helper and add its render target to the page
let app = new Application({ width: 640, height: 360 });
document.body.appendChild(app.view);

// Create window frame
let frame = new Graphics({
  x:320 - 104,
  y:180 - 104
})
.rect(0, 0, 208, 208)
.fill(0x666666)
.stroke({ color: 0xffffff, width: 4, alignment: 0 })

app.stage.addChild(frame);

// Create a graphics object to define our mask
let mask = new Graphics()
// Add the rectangular area to show
 .rect(0,0,200,200)
 .fill(0xffffff);

// Add container that will hold our masked content
let maskContainer = new Container();
// Set the mask to use our graphics object from above
maskContainer.mask = mask;
// Add the mask as a child, so that the mask is positioned relative to its parent
maskContainer.addChild(mask);
// Offset by the window's frame width
maskContainer.position.set(4,4);
// And add the container to the window!
frame.addChild(maskContainer);

// Create contents for the masked container
let text = new Text({
  text:'This text will scroll up and be masked, so you can see how masking works.  Lorem ipsum and all that.\n\n' +
  'You can put anything in the container and it will be masked!',
  style:{
    fontSize: 24,
    fill: 0x1010ff,
    wordWrap: true,
    wordWrapWidth: 180
  },
  x:10
});

maskContainer.addChild(text);

// Add a ticker callback to scroll the text up and down
let elapsed = 0.0;
app.ticker.add((ticker) => {
  // Update the text's y coordinate to scroll it
  elapsed += ticker.deltaTime;
  text.y = 10 + -100.0 + Math.cos(elapsed/50.0) * 100.0;
});

PixiJS 支持两种类型的掩码：

¥There are two types of masks supported by PixiJS:

使用 图形 对象创建任意形状的蒙版 - 功能强大，但不支持抗锯齿

¥Use a Graphics object to create a mask with an arbitrary shape - powerful, but doesn't support anti-aliasing

精灵：使用 精灵 的 Alpha 通道作为遮罩，提供抗锯齿边缘 - Canvas 渲染器不支持

¥Sprite: Use the alpha channel from a Sprite as your mask, providing anti-aliased edging - not supported on the Canvas renderer

过滤

¥Filtering

容器对象的另一个常见用途是作为过滤内容的宿主。滤镜是一项仅限 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.

以下是 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.

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

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