pixijs-scene-container

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Container
is the general-purpose node of the PixiJS v8 scene graph. It holds children and applies transforms, alpha, tint, and blend mode to its whole subtree. Every display object you make will either be a
Container
you're building a branch on, or a leaf (
Sprite
,
Graphics
,
Text
,
Mesh
) that you nest inside one.
Assumes familiarity with
pixijs-scene-core-concepts
.
Container
是PixiJS v8场景图中的通用节点,它可以容纳子对象,并对整个子树应用变换、透明度(alpha)、色调(tint)和混合模式。你创建的每个显示对象要么是用于构建分支的
Container
,要么是嵌套在其中的叶子对象(
Sprite
Graphics
Text
Mesh
)。
使用本技能需先熟悉
pixijs-scene-core-concepts

Quick Start

快速开始

ts
const group = new Container({
  label: "hero-group",
  x: 200,
  y: 150,
  sortableChildren: true,
});

const body = new Sprite(await Assets.load("body.png"));
const head = new Sprite(await Assets.load("head.png"));
head.position.set(0, -40);
head.zIndex = 1;

group.addChild(body, head);
group.pivot.set(group.width / 2, group.height / 2);
group.scale.set(1.5);

app.stage.addChild(group);
Related skills:
pixijs-scene-core-concepts
(scene graph mental model, masking, layers, render groups),
pixijs-scene-sprite
/
pixijs-scene-graphics
/
pixijs-scene-text
/
pixijs-scene-mesh
(leaf objects that go inside containers),
pixijs-events
(
eventMode
, hit testing),
pixijs-math
(Matrix, toGlobal/toLocal detail),
pixijs-performance
(
cacheAsTexture
, culling, render groups).
ts
const group = new Container({
  label: "hero-group",
  x: 200,
  y: 150,
  sortableChildren: true,
});

const body = new Sprite(await Assets.load("body.png"));
const head = new Sprite(await Assets.load("head.png"));
head.position.set(0, -40);
head.zIndex = 1;

group.addChild(body, head);
group.pivot.set(group.width / 2, group.height / 2);
group.scale.set(1.5);

app.stage.addChild(group);
相关技能
pixijs-scene-core-concepts
(场景图思维模型、遮罩、图层、渲染组)、
pixijs-scene-sprite
/
pixijs-scene-graphics
/
pixijs-scene-text
/
pixijs-scene-mesh
(可嵌套在容器中的叶子对象)、
pixijs-events
eventMode
、点击测试)、
pixijs-math
(Matrix、toGlobal/toLocal细节)、
pixijs-performance
cacheAsTexture
、剔除、渲染组)。

Core Patterns

核心模式

Constructor options

构造函数选项

ts
const container = new Container({
  label: "world",
  x: 100,
  y: 50,
  scale: 2,
  rotation: Math.PI / 4,
  alpha: 0.8,
  visible: true,
  tint: 0xffaa00,
  blendMode: "add",
  sortableChildren: true,
  isRenderGroup: true,
  origin: { x: 0, y: 0 },
  boundsArea: new Rectangle(0, 0, 1920, 1080),
});
All
Container
options (
position
,
scale
,
tint
,
label
,
filters
,
zIndex
, etc.) are also valid here — see
skills/pixijs-scene-core-concepts/references/constructor-options.md
.
The
Container
constructor uses
assignWithIgnore
to bulk-copy every field in the options object onto the instance except
children
,
parent
, and
effects
. Any public property of
Container
is a valid constructor option:
cullable
,
cullArea
,
mask
,
filterArea
,
eventMode
,
hitArea
, and so on. The options block above groups the most common ones; see the shared reference above for the full list.
isRenderGroup: true
promotes the container to its own render group so its transforms are applied on the GPU rather than recomputed per-child on the CPU. Use it on stable sub-trees (large static worlds, UI layers). Don't overuse; most scenes don't need explicit render groups and too many hurts performance. Profile before promoting. See
pixijs-scene-core-concepts/references/scene-management.md
.
sortableChildren: true
causes children to be re-sorted by
zIndex
at the next render. See
zIndex
below.
origin
is a first-class v8 transform helper: an
ObservablePoint
that acts as a rotation/scale center without moving the container. Where
pivot
shifts the projection of the local origin in parent space (so changing it displaces the object),
origin
leaves position alone and simply rotates/scales around the specified local point. Accepts
PointData
, a single number (applied to both axes), or can be set live via
container.origin.set(x, y)
. Setting both
pivot
and
origin
on the same container produces compounding behavior and is discouraged; pick one.
boundsArea
forces
getBounds()
to return a fixed rectangle instead of recursively measuring children; it is a performance win for containers with hundreds of cheap, predictable children.
cullable
and
cullArea
are valid constructor options (the
assignWithIgnore
pass copies them like any other field), but they are documented in
pixijs-performance
because culling setup is a performance concern rather than a scene-graph concern.
ts
const container = new Container({
  label: "world",
  x: 100,
  y: 50,
  scale: 2,
  rotation: Math.PI / 4,
  alpha: 0.8,
  visible: true,
  tint: 0xffaa00,
  blendMode: "add",
  sortableChildren: true,
  isRenderGroup: true,
  origin: { x: 0, y: 0 },
  boundsArea: new Rectangle(0, 0, 1920, 1080),
});
所有
Container
选项(
position
scale
tint
label
filters
zIndex
等)均适用于此处——详见
skills/pixijs-scene-core-concepts/references/constructor-options.md
Container
构造函数使用
assignWithIgnore
将选项对象中的所有字段批量复制到实例中,除了
children
parent
effects
Container
的任何公共属性都是有效的构造函数选项:
cullable
cullArea
mask
filterArea
eventMode
hitArea
等。上方选项块列出了最常用的选项;完整列表请参阅上述共享参考文档。
isRenderGroup: true
会将容器升级为独立的渲染组,使其变换在GPU上应用,而非在CPU上为每个子对象重新计算。适用于稳定的子树(大型静态场景、UI层)。请勿过度使用;大多数场景不需要显式渲染组,过多渲染组会影响性能。升级前请先做性能分析。详见
pixijs-scene-core-concepts/references/scene-management.md
sortableChildren: true
会使子对象在下一次渲染时按
zIndex
重新排序。详见下方
zIndex
部分。
origin
是v8中一级的变换辅助工具:一个
ObservablePoint
,可作为旋转/缩放中心且不会移动容器
pivot
会改变父空间中局部原点的投影(因此修改它会使对象位移),而
origin
不会改变位置,只是围绕指定的局部点进行旋转/缩放。接受
PointData
、单个数字(应用于两个轴),也可通过
container.origin.set(x, y)
动态设置。不建议在同一个容器上同时设置
pivot
origin
,这会产生复合行为;请选择其中一个。
boundsArea
强制
getBounds()
返回固定矩形,而非递归测量子对象;对于包含数百个低成本、可预测子对象的容器来说,这是一项性能优化。
cullable
cullArea
是有效的构造函数选项(
assignWithIgnore
会像复制其他字段一样复制它们),但它们在
pixijs-performance
中记录,因为剔除设置属于性能相关问题,而非场景图相关问题。

Leaves vs containers

叶子对象 vs 容器

ts
const parent = new Container();
const sprite = new Sprite(texture);

parent.addChild(sprite);
Only
Container
(and subclasses intended to hold children, like
RenderLayer
) should have children.
Sprite
,
Graphics
,
Text
,
Mesh
,
ParticleContainer
particles, and
DOMContainer
content are leaves by convention in PixiJS v8. Wrap them in a
Container
whenever you need to group things: give the container the layout logic and keep the leaves pure visual data. Adding children to a leaf logs a deprecation warning and is scheduled to become a hard error.
ts
const parent = new Container();
const sprite = new Sprite(texture);

parent.addChild(sprite);
只有
Container
(以及用于容纳子对象的子类,如
RenderLayer
)才能拥有子对象。在PixiJS v8中,
Sprite
Graphics
Text
Mesh
ParticleContainer
粒子和
DOMContainer
内容默认是叶子对象。当你需要分组时,请将它们包装在
Container
中:让容器处理布局逻辑,叶子对象仅保留纯视觉数据。向叶子对象添加子对象会记录弃用警告,并计划在未来版本中变为硬错误。

Adding and removing children

添加和移除子对象

ts
const parent = new Container();

parent.addChild(a, b, c);
parent.addChildAt(d, 0);
parent.swapChildren(a, b);
parent.setChildIndex(c, 0);

parent.removeChild(b);
parent.removeChildAt(0);
parent.removeChildren();

parent.removeChildren(0, 2);
addChild
accepts any number of children and returns the first one. Children render in array order: index 0 is drawn first (behind), the last index is drawn last (in front).
addChildAt
inserts at a specific index;
setChildIndex
moves an existing child;
swapChildren
exchanges two children's positions.
removeChildren(beginIndex?, endIndex?)
removes a slice and returns the removed array.
Calling
addChildAt
with a child that already belongs to the same container silently moves it to the new index. No
added
/
childAdded
/
removed
/
childRemoved
events fire, because the parent-child relationship didn't change. Events only fire when the child comes from a different parent (or from no parent).
For reparenting that preserves world transform (so the child doesn't visually jump), use
reparentChild
/
reparentChildAt
. For swapping a child in place while copying the old child's local transform, use
replaceChild
.
ts
const parent = new Container();

parent.addChild(a, b, c);
parent.addChildAt(d, 0);
parent.swapChildren(a, b);
parent.setChildIndex(c, 0);

parent.removeChild(b);
parent.removeChildAt(0);
parent.removeChildren();

parent.removeChildren(0, 2);
addChild
接受任意数量的子对象,并返回第一个子对象。子对象按数组顺序渲染:索引0最先绘制(在底层),最后一个索引最后绘制(在顶层)。
addChildAt
在指定索引处插入;
setChildIndex
移动现有子对象;
swapChildren
交换两个子对象的位置。
removeChildren(beginIndex?, endIndex?)
移除指定范围内的子对象,并返回被移除的数组。
如果调用
addChildAt
时传入的子对象已属于同一个容器,它会静默地将子对象移动到新索引。此时不会触发
added
/
childAdded
/
removed
/
childRemoved
事件,因为父子关系没有改变。只有当子对象来自不同父对象(或无父对象)时才会触发事件。
如需在重新父化时保留世界变换(避免子对象视觉上跳变),请使用
reparentChild
/
reparentChildAt
。如需替换子对象并复制旧子对象的局部变换,请使用
replaceChild

Transform properties

变换属性

ts
const obj = new Container();

obj.x = 100;
obj.y = 200;
obj.position.set(100, 200);

obj.scale.set(2);
obj.scale = 2;

obj.rotation = Math.PI / 4;
obj.angle = 45;

obj.pivot.set(50, 50);
obj.skew.set(0.1, 0.2);

obj.alpha = 0.5;
obj.tint = 0xff0000;
obj.visible = false;
obj.renderable = false;
  • position
    ,
    scale
    ,
    pivot
    ,
    skew
    are
    ObservablePoint
    s. Assigning
    scale = 2
    is valid and sets both axes.
  • rotation
    is radians;
    angle
    is degrees; they are aliases that stay in sync.
  • pivot
    sets the point in local space that maps to
    position
    in parent space; changing it both moves and rotates the container.
  • alpha
    and
    tint
    multiply down through children.
    blendMode
    applies to this container's draw instructions.
  • visible = false
    skips rendering and transform updates.
    renderable = false
    skips rendering but still updates transforms (use when you need
    getBounds()
    or hit-testing without drawing).
ts
const obj = new Container();

obj.x = 100;
obj.y = 200;
obj.position.set(100, 200);

obj.scale.set(2);
obj.scale = 2;

obj.rotation = Math.PI / 4;
obj.angle = 45;

obj.pivot.set(50, 50);
obj.skew.set(0.1, 0.2);

obj.alpha = 0.5;
obj.tint = 0xff0000;
obj.visible = false;
obj.renderable = false;
  • position
    scale
    pivot
    skew
    均为
    ObservablePoint
    。赋值
    scale = 2
    是有效的,会同时设置两个轴。
  • rotation
    使用弧度;
    angle
    使用角度;它们是同步的别名。
  • pivot
    设置局部空间中映射到父空间
    position
    的点;修改它会同时移动和旋转容器。
  • alpha
    tint
    会向下传递给子对象。
    blendMode
    应用于该容器的绘制指令。
  • visible = false
    会跳过渲染和变换更新。
    renderable = false
    会跳过渲染,但仍会更新变换(适用于需要
    getBounds()
    或点击测试但不需要绘制的场景)。

zIndex and sortableChildren

zIndex与sortableChildren

ts
const world = new Container({ sortableChildren: true });

const ground = new Sprite(groundTexture);
ground.zIndex = 0;

const player = new Sprite(playerTexture);
player.zIndex = 10;

const ui = new Sprite(uiTexture);
ui.zIndex = 100;

world.addChild(ground, player, ui);
When
sortableChildren
is
true
, the container re-sorts its children by
zIndex
before the next render. Changing any child's
zIndex
automatically re-marks the parent as needing sort. Sort only what you need to sort; leaving
sortableChildren
off is cheaper. If you want full manual control, call
container.sortChildren()
yourself after changing
zIndex
values.
For render-order control that is decoupled from the hierarchy (children keep their logical parent for transforms but render at a different z), use
RenderLayer
. See
pixijs-scene-core-concepts/references/scene-management.md
.
ts
const world = new Container({ sortableChildren: true });

const ground = new Sprite(groundTexture);
ground.zIndex = 0;

const player = new Sprite(playerTexture);
player.zIndex = 10;

const ui = new Sprite(uiTexture);
ui.zIndex = 100;

world.addChild(ground, player, ui);
sortableChildren
true
时,容器会在下一次渲染前按
zIndex
重新排序其子对象。修改任何子对象的
zIndex
会自动标记父容器需要重新排序。仅对需要排序的内容启用该功能;关闭
sortableChildren
性能更优。如果需要完全手动控制,请在修改
zIndex
值后自行调用
container.sortChildren()
如需与层级解耦的渲染顺序控制(子对象保留逻辑父对象用于变换,但在不同z轴层级渲染),请使用
RenderLayer
。详见
pixijs-scene-core-concepts/references/scene-management.md

Bounds and coordinate conversion

边界与坐标转换

ts
const bounds = container.getBounds();
console.log(bounds.x, bounds.y, bounds.width, bounds.height);

const rect = container.getBounds().rectangle;

const local = new Point(10, 20);
const world = container.toGlobal(local);
const backToLocal = container.toLocal(world);

const selfPos = container.getGlobalPosition();
getBounds()
returns a
Bounds
object (not a
Rectangle
); it exposes
x
,
y
,
width
,
height
, and a
.rectangle
getter for APIs that need an actual
Rectangle
. The signature is
getBounds(skipUpdate?: boolean, bounds?: Bounds)
— pass
true
as the first arg to skip the forced transform update, and an optional
Bounds
instance as the second arg to avoid allocating a new one.
toGlobal(point)
converts a point in this container's local space to scene-root space.
toLocal(point, from?)
converts from another container's local space (or global space if
from
is omitted).
getGlobalPosition()
is shorthand for
parent.toGlobal(this._position)
.
ts
const bounds = container.getBounds();
console.log(bounds.x, bounds.y, bounds.width, bounds.height);

const rect = container.getBounds().rectangle;

const local = new Point(10, 20);
const world = container.toGlobal(local);
const backToLocal = container.toLocal(world);

const selfPos = container.getGlobalPosition();
getBounds()
返回
Bounds
对象(而非
Rectangle
);它暴露了
x
y
width
height
,以及
.rectangle
getter,供需要实际
Rectangle
的API使用。其签名为
getBounds(skipUpdate?: boolean, bounds?: Bounds)
——第一个参数传入
true
可跳过强制变换更新,第二个参数传入可选的
Bounds
实例可避免分配新对象。
toGlobal(point)
将该容器局部空间中的点转换为场景根空间中的点。
toLocal(point, from?)
将另一个容器局部空间中的点(如果省略
from
则为全局空间)转换为当前容器的局部空间。
getGlobalPosition()
parent.toGlobal(this._position)
的简写。

Sizing

尺寸设置

ts
const sprite = new Sprite(texture);

sprite.setSize(200, 100);
const { width, height } = sprite.getSize();
setSize
adjusts
scale
so the container's bounds fit the requested pixel size, in one operation. Setting
.width
and
.height
individually works, but each assignment triggers a separate bounds recomputation; prefer
setSize
when changing both axes.
ts
const sprite = new Sprite(texture);

sprite.setSize(200, 100);
const { width, height } = sprite.getSize();
setSize
会调整
scale
,使容器的边界适配请求的像素尺寸,一步完成操作。单独设置
.width
.height
也可行,但每次赋值都会触发单独的边界重新计算;修改两个轴时优先使用
setSize

Container events

容器事件

ts
const parent = new Container();

parent.on("childAdded", (child, container, index) => {
  console.log("added at", index, child.label);
});

parent.on("childRemoved", (child, container, index) => {
  console.log("removed from", index);
});

const child = new Container();
child.on("added", (newParent) => console.log("entered", newParent.label));
child.on("removed", (oldParent) => console.log("left", oldParent.label));
child.on("visibleChanged", (visible) => console.log("visible:", visible));
child.on("destroyed", (destroyed) => console.log("gone", destroyed.label));

parent.addChild(child);
EventFires onArguments
childAdded
the parent receiving the child
(child, container, index)
childRemoved
the parent losing the child
(child, container, index)
added
the child that was attached
(parent)
removed
the child that was detached
(parent)
destroyed
the destroyed container
(container)
visibleChanged
the container whose
visible
flipped
(visible)
These are emitted on the
EventEmitter
side of
Container
; do not confuse them with pointer events from
pixijs-events
.
destroyed
fires after internal cleanup but before listeners are removed, so by the time your handler runs
position
,
scale
,
pivot
,
origin
,
skew
, and
parent
have already been nulled, and
children
has been emptied (length 0, but the array reference itself is not nulled). Capture any data you need from the container before calling
destroy()
, not inside the handler.
ts
const parent = new Container();

parent.on("childAdded", (child, container, index) => {
  console.log("added at", index, child.label);
});

parent.on("childRemoved", (child, container, index) => {
  console.log("removed from", index);
});

const child = new Container();
child.on("added", (newParent) => console.log("entered", newParent.label));
child.on("removed", (oldParent) => console.log("left", oldParent.label));
child.on("visibleChanged", (visible) => console.log("visible:", visible));
child.on("destroyed", (destroyed) => console.log("gone", destroyed.label));

parent.addChild(child);
事件名称触发对象参数列表
childAdded
接收子对象的父容器
(child, container, index)
childRemoved
失去子对象的父容器
(child, container, index)
added
被添加的子对象
(parent)
removed
被移除的子对象
(parent)
destroyed
被销毁的容器
(container)
visibleChanged
visible
属性变化的容器
(visible)
这些事件在
Container
EventEmitter
侧触发;请勿与
pixijs-events
中的指针事件混淆。
destroyed
事件在内部清理完成后、监听器移除前触发,因此当你的处理函数运行时,
position
scale
pivot
origin
skew
parent
已被置空,
children
已被清空(长度为0,但数组引用本身未被置空)。请在调用
destroy()
之前捕获容器所需的任何数据,而非在处理函数内部。

Per-frame updates with onRender

使用onRender进行每帧更新

ts
const container = new Container();

container.onRender = (renderer) => {
  container.rotation += 0.01;
};

container.onRender = null;
onRender
runs every frame while the container is being rendered, and receives the active
Renderer
. Use it for lightweight animation or per-frame updates tied to a specific container. In v7 this pattern was done by overriding
updateTransform
, which no longer runs every frame in v8. Set
onRender = null
to detach the callback.
ts
const container = new Container();

container.onRender = (renderer) => {
  container.rotation += 0.01;
};

container.onRender = null;
onRender
会在容器被渲染时每帧运行一次,并接收当前的
Renderer
。用于轻量级动画或与特定容器绑定的每帧更新。在v7中,此模式通过重写
updateTransform
实现,但在v8中该方法不再每帧运行。设置
onRender = null
可解绑回调。

Finding and removing from parent

查找子对象与从父容器移除

ts
const player = world.getChildByLabel("player");
const enemies = world.getChildrenByLabel(/enemy-\d+/, true);

const bounds = hud.getLocalBounds();

oldSprite.removeFromParent();
  • getChildByLabel(label, deep?)
    — first match by string or
    RegExp
    . Pass
    true
    for a recursive search.
  • getChildrenByLabel(label, deep?, out?)
    — all matches. Accepts an optional reusable output array.
  • getLocalBounds()
    — bounds in this container's own coordinate space, ignoring parent transforms. Cheaper than
    getBounds()
    for self-contained layout math.
  • removeFromParent()
    — detaches
    this
    from its current parent (no-op if already orphaned).
ts
const player = world.getChildByLabel("player");
const enemies = world.getChildrenByLabel(/enemy-\d+/, true);

const bounds = hud.getLocalBounds();

oldSprite.removeFromParent();
  • getChildByLabel(label, deep?)
    ——按字符串或
    RegExp
    查找第一个匹配项。传入
    true
    可进行递归搜索。
  • getChildrenByLabel(label, deep?, out?)
    ——查找所有匹配项。接受可选的可复用输出数组。
  • getLocalBounds()
    ——该容器自身坐标空间中的边界,忽略父容器变换。对于自包含的布局计算,比
    getBounds()
    更高效。
  • removeFromParent()
    ——将当前对象从其父容器中分离(如果已无父容器则无操作)。

Destroy

销毁

ts
container.destroy();

container.destroy({
  children: true,
  texture: true,
  textureSource: true,
});

console.log(container.destroyed);
By default
destroy()
unlinks this container from its parent and tears down its own state. Pass
{ children: true }
to recursively destroy every descendant; this is the usual call for killing a whole subtree.
texture: true
and
textureSource: true
additionally destroy the GPU resources referenced by leaf children (useful for sprites whose textures you loaded just for them). If
cacheAsTexture
is on, disable it with
container.cacheAsTexture(false)
before destroying.
ts
container.destroy();

container.destroy({
  children: true,
  texture: true,
  textureSource: true,
});

console.log(container.destroyed);
默认情况下,
destroy()
会将该容器与父容器解绑,并销毁自身状态。传入
{ children: true }
可递归销毁所有后代;这是销毁整个子树的常用调用方式。
texture: true
textureSource: true
会额外销毁叶子子对象引用的GPU资源(适用于仅为其加载纹理的精灵)。如果启用了
cacheAsTexture
,请在销毁前调用
container.cacheAsTexture(false)
禁用它。

Common Mistakes

常见错误

[CRITICAL] Adding children to leaf scene objects

[严重] 向叶子场景对象添加子对象

Wrong:
ts
const sprite = new Sprite(texture);
const overlay = new Sprite(overlayTexture);
sprite.addChild(overlay);
Correct:
ts
const group = new Container();
const sprite = new Sprite(texture);
const overlay = new Sprite(overlayTexture);
group.addChild(sprite, overlay);
Sprites, Graphics, Text, and Mesh are leaves. Adding children to them logs a deprecation warning now and will be an error in a future version. Always wrap them in a
Container
when you need grouping.
错误示例:
ts
const sprite = new Sprite(texture);
const overlay = new Sprite(overlayTexture);
sprite.addChild(overlay);
正确示例:
ts
const group = new Container();
const sprite = new Sprite(texture);
const overlay = new Sprite(overlayTexture);
group.addChild(sprite, overlay);
Sprite、Graphics、Text和Mesh是叶子对象。向它们添加子对象会记录弃用警告,并将在未来版本中变为错误。当你需要分组时,请始终将它们包装在
Container
中。

[HIGH] Expecting getBounds() to return a Rectangle

[高风险] 期望getBounds()返回Rectangle

Wrong:
ts
const rect = container.getBounds();
rect.contains(x, y); // TypeError: contains is not a function
Correct:
ts
const rect = container.getBounds().rectangle;
rect.contains(x, y);

const bounds = container.getBounds();
console.log(bounds.width, bounds.height);
getBounds()
returns a
Bounds
instance in v8. Its basic getters (
x
,
y
,
width
,
height
) work, but for
Rectangle
-specific methods like
.contains()
or passing to APIs that require a
Rectangle
, read the
.rectangle
property.
错误示例:
ts
const rect = container.getBounds();
rect.contains(x, y); // TypeError: contains is not a function
正确示例:
ts
const rect = container.getBounds().rectangle;
rect.contains(x, y);

const bounds = container.getBounds();
console.log(bounds.width, bounds.height);
在v8中,
getBounds()
返回
Bounds
实例。它的基本getter(
x
y
width
height
)可用,但对于
.contains()
Rectangle
特定方法,或需要传入
Rectangle
的API,请读取
.rectangle
属性。

[HIGH] Using cacheAsBitmap instead of cacheAsTexture

[高风险] 使用cacheAsBitmap而非cacheAsTexture

Wrong:
ts
container.cacheAsBitmap = true;
Correct:
ts
container.cacheAsTexture(true);
cacheAsBitmap
(v7 property) was renamed to
cacheAsTexture()
(a method) in v8. Always disable it with
cacheAsTexture(false)
before calling
destroy()
.
错误示例:
ts
container.cacheAsBitmap = true;
正确示例:
ts
container.cacheAsTexture(true);
v7中的属性
cacheAsBitmap
在v8中重命名为方法
cacheAsTexture()
。调用
destroy()
前请始终使用
cacheAsTexture(false)
禁用它。

[MEDIUM] Using container.name instead of container.label

[中风险] 使用container.name而非container.label

name
was renamed to
label
in v8. The old property still works as a deprecated alias;
getChildByLabel
is the v8 way to look up children by name.
在v8中,
name
已重命名为
label
。旧属性仍可作为弃用别名使用;
getChildByLabel
是v8中按名称查找子对象的方式。

[MEDIUM] Setting both pivot and origin on the same container

[中风险] 在同一个容器上同时设置pivot和origin

Pivot shifts the projection of the local origin in parent space (moves the object as a side-effect of changing the rotation center). Origin changes the rotation/scale center without displacement. Setting both on the same container produces unexpected compounding; pick one.
Pivot会改变父空间中局部原点的投影(修改旋转中心时会导致对象位移)。Origin会改变旋转/缩放中心但不会导致位移。在同一个容器上同时设置两者会产生意外的复合行为;请选择其中一个。

API Reference

API参考