pixijs-scene-sprite

PixiJS 针对不同绘制任务提供了三种精灵类。Sprite 是用于绘制图像的默认叶节点；NineSliceSprite 是可调整大小的 UI 面板变体，可保留边角图案；TilingSprite 会在指定区域重复平铺纹理。AnimatedSprite 是 Sprite 的子类，可循环播放纹理帧以实现基于帧的动画。

假设你已熟悉 pixijs-scene-core-concepts。所有精灵类都是叶节点；它们不能包含子节点。若要将多个精灵分组，请将它们包装在 Container 中。

快速入门

const texture = await Assets.load("bunny.png");

const sprite = new Sprite({
  texture,
  anchor: 0.5,
  tint: 0xff8888,
});
sprite.x = app.screen.width / 2;
sprite.y = app.screen.height / 2;

app.stage.addChild(sprite);

由于 app.screen.width / 2 取决于渲染器的实时尺寸，因此位置是在构造后设置的。字面量位置可以通过 x/y 直接传入选项对象（继承自 Container）。

相关技能： pixijs-scene-core-concepts（叶节点、变换）、pixijs-assets（纹理加载）、pixijs-scene-particle-container（数千个精灵）、pixijs-performance（精灵图集、批处理）。

变体

变体	适用场景	权衡	参考
Sprite	在指定位置绘制单个纹理	尺寸固定为纹理尺寸	references/sprite.md
AnimatedSprite	使用纹理数组或精灵图集实现基于帧的动画	仅支持预渲染帧；不支持补间	references/animated-sprite.md
NineSliceSprite	可调整大小的 UI 面板、按钮、对话框边框	边框宽度固定；中心区域会拉伸	references/nineslice-sprite.md
TilingSprite	滚动背景、视差效果、重复图案	重复使用单个纹理；通过 tilePosition 滚动	references/tiling-sprite.md

AnimatedSprite 是 Sprite 的子类；所有 Sprite 属性（锚点、色调、位置）均适用。

每种变体的构造选项都记录在对应的子参考文件中（references/{variant}.md）。所有变体也接受 Container 选项（position、scale、tint、label、filters、zIndex 等）——请参阅 skills/pixijs-scene-core-concepts/references/constructor-options.md。

如何选择

• “我想在指定位置绘制单张图片” → Sprite。这是 90% 的 2D 游戏和应用内容的默认选择。
• “我想让角色按一系列帧播放动画” → AnimatedSprite。通过 Assets 加载精灵图集，并传入 sheet.animations['walk']。请参阅 references/animated-sprite.md。
• “我想要一个调整大小时边框不会被拉伸的 UI 按钮/面板” → NineSliceSprite。设置边框宽度，然后设置 width/height。请参阅 references/nineslice-sprite.md。
• “我想要一个滚动的重复背景” → TilingSprite。对 tilePosition 进行动画处理以实现滚动。请参阅 references/tiling-sprite.md。
• “我想要数千个相同的精灵” → 使用 Particle 实例和 ParticleContainer（参见 pixijs-scene-particle-container），而不是普通精灵。
• “我想绘制形状或路径” → 使用 Graphics（参见 pixijs-scene-graphics），而不是精灵。

快速概念

Anchor 与 pivot

Sprite.anchor 的取值范围为归一化的 [0, 1]，只会移动纹理的绘制原点，不会产生位置偏移。Container.pivot 使用像素坐标，会同时移动变换原点和视觉位置。若要将精灵居中，请始终使用 anchor.set(0.5)。

创建前先加载

Sprite.from(id) 只会读取 Assets 缓存，不会获取资源。请务必先执行 await Assets.load(...)，或将返回的 Texture 直接传给 new Sprite(texture)。

动态纹理

纹理加载后，修改其 frame 或替换其源不会自动通知精灵。设置一次 texture.dynamic = true，或者在修改后手动调用 sprite['onViewUpdate']()。

常见错误

[HIGH] 使用 Texture.from(url) 加载

错误：

const texture = Texture.from("https://example.com/image.png");

正确：

const texture = await Assets.load("https://example.com/image.png");

在 v8 中，Texture.from() 只会读取缓存。请先使用 Assets.load()；其返回值就是纹理。

[HIGH] 混淆 anchor 和 pivot

错误：

sprite.pivot.set(sprite.width / 2, sprite.height / 2);

正确：

sprite.anchor.set(0.5);

anchor 只会偏移绘制原点。pivot 会同时偏移变换原点和视觉位置，导致精灵意外移动。

[HIGH] 旧的 NineSlicePlane 名称

在 v8 中，NineSlicePlane 更名为 NineSliceSprite，并改用选项对象构造函数：new NineSliceSprite({ texture, leftWidth, topHeight, rightWidth, bottomHeight })。

[MEDIUM] 向精灵添加子项

Sprite、NineSliceSprite 和 TilingSprite 都将 allowChildren = false。如需将精灵与其他内容分组，请使用 Container 包装。

API 参考

• 精灵
• 精灵选项
• 动画精灵
• 九宫格精灵
• 平铺精灵
• 纹理