pixijs-scene-sprite

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PixiJS has three sprite classes for different drawing tasks.

Sprite

is the default image-drawing leaf;

NineSliceSprite

is a resizable UI-panel variant that preserves corner art;

TilingSprite

repeats a texture across an area. The

AnimatedSprite

subclass of

Sprite

cycles through texture frames for frame-based animation.

Assumes familiarity with

pixijs-scene-core-concepts

. All sprite classes are leaf nodes; they cannot have children. Wrap multiple sprites in a

Container

to group them.

PixiJS有三种用于不同绘图任务的精灵类。

Sprite

是默认的图像绘制叶节点；

NineSliceSprite

是可调整大小的UI面板变体，能保留边角样式；

TilingSprite

会在指定区域重复纹理。

AnimatedSprite

是

Sprite

的子类，可循环切换纹理帧以实现逐帧动画。

本文假设你已熟悉

pixijs-scene-core-concepts

。所有精灵类都是叶节点，无法拥有子元素。若要将多个精灵分组，需将它们包裹在

Container

中。

Quick Start

快速开始

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);

Position is set after construction because

app.screen.width / 2

depends on the live renderer size. Literal positions can go directly in the options object via

(inherited from

Container

Related skills:

pixijs-scene-core-concepts

(leaves, transforms),

pixijs-assets

(texture loading),

pixijs-scene-particle-container

(thousands of sprites),

pixijs-performance

(spritesheets, batching).

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

依赖于渲染器的实时尺寸。固定位置可直接通过

（继承自

Container

）写入选项对象。

相关技能：

pixijs-scene-core-concepts

（叶节点、变换）、

pixijs-assets

（纹理加载）、

pixijs-scene-particle-container

（批量精灵）、

pixijs-performance

（精灵表、批处理）。

Variants

变体对比

Variant	Use when	Trade-offs	Reference
`Sprite`	Draw a single texture at a position	Fixed size = texture size	references/sprite.md
`AnimatedSprite`	Frame-based animation from a texture array or spritesheet	Pre-rendered frames only; no tweening	references/animated-sprite.md
`NineSliceSprite`	Resizable UI panels, buttons, dialog frames	Border width is fixed; center stretches	references/nineslice-sprite.md
`TilingSprite`	Scrolling backgrounds, parallax, repeating patterns	Single texture repeated; `tilePosition` scrolls	references/tiling-sprite.md

AnimatedSprite

is a subclass of

Sprite

; all

Sprite

properties (anchor, tint, position) apply.

Each variant's constructor options are documented in its sub-reference file (

references/{variant}.md

). All variants also accept the

Container

options (

position

scale

tint

label

filters

zIndex

, etc.) — see

skills/pixijs-scene-core-concepts/references/constructor-options.md

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

AnimatedSprite

是

Sprite

的子类，所有

Sprite

的属性（anchor、tint、position）均适用。

每个变体的构造函数选项可在其子参考文档中查看（

references/{variant}.md

）。所有变体也支持

Container

的选项（

position

、

scale

、

tint

、

label

、

filters

、

zIndex

等）——详见

skills/pixijs-scene-core-concepts/references/constructor-options.md

。

When to use what

场景选型指南

"I want to draw a single image at a position" →
```
Sprite
```
. The default choice for 90% of 2D game and app content.
"I want to animate a character through a series of frames" →
```
AnimatedSprite
```
. Load a spritesheet via Assets and pass
```
sheet.animations['walk']
```
. See
```
references/animated-sprite.md
```
.
"I want a UI button/panel that resizes without stretching the borders" →
```
NineSliceSprite
```
. Set border widths, then set
```
width
```
/
```
height
```
. See
```
references/nineslice-sprite.md
```
.
"I want a scrolling repeating background" →
```
TilingSprite
```
. Animate
```
tilePosition
```
to scroll. See
```
references/tiling-sprite.md
```
.
"I want thousands of identical sprites" → Use
```
ParticleContainer
```
with
```
Particle
```
instances (see
```
pixijs-scene-particle-container
```
), not plain sprites.
"I want to draw shapes or paths" → Use
```
Graphics
```
(see
```
pixijs-scene-graphics
```
), not a sprite.

「我想在指定位置绘制单张图片」 → 使用
```
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
```
。
「我想要创建数千个相同的精灵」 → 使用
```
ParticleContainer
```
搭配
```
Particle
```
实例（详见
```
pixijs-scene-particle-container
```
），而非普通精灵。
「我想要绘制形状或路径」 → 使用
```
Graphics
```
（详见
```
pixijs-scene-graphics
```
），而非精灵。

Quick concepts

核心概念速览

Anchor vs pivot

Anchor与Pivot的区别

Sprite.anchor

is normalized

[0, 1]

and shifts only the texture draw origin; no position offset.

Container.pivot

is pixel-space and shifts both the transform origin and the visual position. For centering a sprite, always use

anchor.set(0.5)

Sprite.anchor

是归一化值

[0, 1]

，仅改变纹理的绘制原点，不会产生位置偏移。

Container.pivot

是像素空间的值，会同时改变变换原点和视觉位置。若要居中精灵，始终使用

anchor.set(0.5)

。

Loading before creating

先加载再创建

Sprite.from(id)

only reads the Assets cache; it does not fetch. Always

await Assets.load(...)

first, or pass the returned

Texture

directly to

new Sprite(texture)

Sprite.from(id)

仅读取Assets缓存，不会发起请求。务必先执行

await Assets.load(...)

，或直接将返回的

Texture

传入

new Sprite(texture)

。

Dynamic textures

动态纹理

Once a texture is loaded, modifying its

frame

or swapping its source does not automatically notify sprites. Set

texture.dynamic = true

once, or call

sprite['onViewUpdate']()

manually after changes.

纹理加载完成后，修改其

frame

或切换源不会自动通知精灵。只需设置一次

texture.dynamic = true

，或在修改后手动调用

sprite['onViewUpdate']()

。

Common Mistakes

常见错误

[HIGH] Using

Texture.from(url)

to load

[高风险] 使用

Texture.from(url)

加载资源

Wrong:

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

Correct:

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

Texture.from()

only reads the cache in v8. Use

Assets.load()

first; its return value is the texture.

错误示例：

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] Confusing anchor and pivot

[高风险] 混淆Anchor与Pivot

Wrong:

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

Correct:

sprite.anchor.set(0.5);

anchor

shifts only the draw origin.

pivot

shifts the transform origin AND the visual position, causing the sprite to move unexpectedly.

错误示例：

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

正确示例：

sprite.anchor.set(0.5);

anchor

仅改变绘制原点。

pivot

会同时改变变换原点和视觉位置，导致精灵位置意外偏移。

[HIGH] Old

NineSlicePlane

name

[高风险] 使用旧名称

NineSlicePlane

NineSlicePlane

was renamed to

NineSliceSprite

in v8 and switched to an options-object constructor:

new NineSliceSprite({ texture, leftWidth, topHeight, rightWidth, bottomHeight })

在v8版本中，

NineSlicePlane

已更名为

NineSliceSprite

，并改用选项对象构造函数：

new NineSliceSprite({ texture, leftWidth, topHeight, rightWidth, bottomHeight })

。

[MEDIUM] Adding children to a sprite

[中风险] 为精灵添加子元素

Sprite

NineSliceSprite

, and

TilingSprite

all set

allowChildren = false

. Wrap in a

Container

to group sprites with other content.

Sprite

、

NineSliceSprite

和

TilingSprite

均设置了

allowChildren = false

。若要将精灵与其他内容分组，需将它们包裹在

Container

中。

pixijs-scene-sprite

Original

Translation

Quick Start

快速开始

Variants

变体对比

When to use what

场景选型指南

Quick concepts

核心概念速览

Anchor vs pivot

Anchor与Pivot的区别

Loading before creating

先加载再创建

Dynamic textures

动态纹理

Common Mistakes

常见错误

[HIGH] Using
`Texture.from(url)`
to load

[高风险] 使用
`Texture.from(url)`
加载资源

[HIGH] Confusing anchor and pivot

[高风险] 混淆Anchor与Pivot

[HIGH] Old
`NineSlicePlane`
name

[高风险] 使用旧名称
`NineSlicePlane`

[MEDIUM] Adding children to a sprite

[中风险] 为精灵添加子元素

API Reference

API参考

pixijs-scene-sprite

Original

Translation

Quick Start

快速开始

Variants

变体对比

When to use what

场景选型指南

Quick concepts

核心概念速览

Anchor vs pivot

Anchor与Pivot的区别

Loading before creating

先加载再创建

Dynamic textures

动态纹理

Common Mistakes

常见错误

[HIGH] Using Texture.from(url) to load

[高风险] 使用Texture.from(url)加载资源

[HIGH] Confusing anchor and pivot

[高风险] 混淆Anchor与Pivot

[HIGH] Old NineSlicePlane name

[高风险] 使用旧名称NineSlicePlane

[MEDIUM] Adding children to a sprite

[中风险] 为精灵添加子元素

API Reference

API参考

[HIGH] Using
`Texture.from(url)`
to load

[高风险] 使用
`Texture.from(url)`
加载资源

[HIGH] Old
`NineSlicePlane`
name

[高风险] 使用旧名称
`NineSlicePlane`