容器

¥Container

Container 类是 PixiJS 场景图形系统的基础。容器充当场景对象组，允许你构建复杂的层级结构、组织渲染图层，并对对象组应用变换或效果。

¥The Container class is the foundation of PixiJS's scene graph system. Containers act as groups of scene objects, allowing you to build complex hierarchies, organize rendering layers, and apply transforms or effects to groups of objects.

什么是容器？

¥What Is a Container?

Container 是一个通用节点，可以容纳其他显示对象，包括其他容器。它用于构建场景、应用变换以及管理渲染和交互。

¥A Container is a general-purpose node that can hold other display objects, including other containers. It is used to structure your scene, apply transformations, and manage rendering and interaction.

容器不直接渲染。相反，它们将渲染委托给它们的子节点。

¥Containers are not rendered directly. Instead, they delegate rendering to their children.

import { Container, Sprite } from 'pixi.js';

const group = new Container();
const sprite = Sprite.from('bunny.png');

group.addChild(sprite);

管理子级

¥Managing Children

PixiJS 提供了一个强大的 API，用于在容器中添加、移除、重新排序和交换子元素：

¥PixiJS provides a robust API for adding, removing, reordering, and swapping children in a container:

const container = new Container();
const child1 = new Container();
const child2 = new Container();

container.addChild(child1, child2);
container.removeChild(child1);
container.addChildAt(child1, 0);
container.swapChildren(child1, child2);

你还可以通过索引移除子项，或移除一定范围内的所有子项：

¥You can also remove a child by index or remove all children within a range:

container.removeChildAt(0);
container.removeChildren(0, 2);

要在将子对象移动到其他容器时保持其世界变换，请使用 reparentChild 或 reparentChildAt：

¥To keep a child’s world transform while moving it to another container, use reparentChild or reparentChildAt:

otherContainer.reparentChild(child);

事件

¥Events

容器在添加或删除子项时会触发事件：

¥Containers emit events when children are added or removed:

group.on('childAdded', (child, parent, index) => { ... });
group.on('childRemoved', (child, parent, index) => { ... });

查找子级

¥Finding Children

容器支持使用辅助方法通过 label 搜索子项：

¥Containers support searching children by label using helper methods:

const child = new Container({ label: 'enemy' });
container.addChild(child);
container.getChildByLabel('enemy');
container.getChildrenByLabel(/^enemy/); // all children whose label starts with "enemy"

设置 deep = true 以递归搜索所有后代。

¥Set deep = true to search recursively through all descendants.

container.getChildByLabel('ui', true);

排序子元素

¥Sorting Children

使用 zIndex 和 sortableChildren 控制容器内的渲染顺序：

¥Use zIndex and sortableChildren to control render order within a container:

child1.zIndex = 1;
child2.zIndex = 10;
container.sortableChildren = true;

如果需要，请调用 sortChildren() 手动重新排序：

¥Call sortChildren() to manually re-sort if needed:

container.sortChildren();

信息

请谨慎使用此功能，因为对于大量子项，排序可能会很昂贵。

¥Use this feature sparingly, as sorting can be expensive for large numbers of children.

使用渲染组进行优化

¥Optimizing with Render Groups

可以通过设置 isRenderGroup = true 或调用 enableRenderGroup() 将容器提升为渲染组。

¥Containers can be promoted to render groups by setting isRenderGroup = true or calling enableRenderGroup().

将渲染组用于 UI 层、粒子系统或大型移动子树。更多详情，请参阅 渲染组指南。

¥Use render groups for UI layers, particle systems, or large moving subtrees. See the Render Groups guide for more details.

const uiLayer = new Container({ isRenderGroup: true });

缓存为纹理

¥Cache as Texture

PixiJS 中的 cacheAsTexture 函数是优化应用渲染的强大工具。通过将容器及其子项渲染为纹理，cacheAsTexture 可以显著提高静态或不经常更新的容器的性能。

¥The cacheAsTexture function in PixiJS is a powerful tool for optimizing rendering in your applications. By rendering a container and its children to a texture, cacheAsTexture can significantly improve performance for static or infrequently updated containers.

设置 container.cacheAsTexture() 时，容器将渲染为纹理。后续渲染将重用此纹理，而不是渲染容器的所有单个子元素。这种方法对于具有许多静态元素的容器特别有用，因为它减少了渲染工作量。

¥When you set container.cacheAsTexture(), the container is rendered to a texture. Subsequent renders reuse this texture instead of rendering all the individual children of the container. This approach is particularly useful for containers with many static elements, as it reduces the rendering workload.

注意

cacheAsTexture 是 PixiJS v8 中与之前的 cacheAsBitmap 功能相同的功能。如果你从 v7 或更早版本迁移，只需在代码中将 cacheAsBitmap 替换为 cacheAsTexture。

¥cacheAsTexture is PixiJS v8's equivalent of the previous cacheAsBitmap functionality. If you're migrating from v7 or earlier, simply replace cacheAsBitmap with cacheAsTexture in your code.

const container = new Container();
const sprite = Sprite.from('bunny.png');
container.addChild(sprite);

// enable cache as texture
container.cacheAsTexture();

// update the texture if the container changes
container.updateCacheTexture();

// disable cache as texture
container.cacheAsTexture(false);

有关更高级的用法，包括设置缓存选项和处理动态内容，请参阅 缓存为纹理指南。

¥For more advanced usage, including setting cache options and handling dynamic content, refer to the Cache as Texture guide.

---

API 参考

¥API Reference

• 容器

  ¥Container

• ContainerOptions

• RenderContainer