PixiJS v8 NineSliceSprite 实战指南:九宫格缩放实现任意尺寸不失真的 UI 面板与按钮
PixiJS v8 NineSliceSprite 实战指南:九宫格缩放实现任意尺寸不失真的 UI 面板与按钮
NineSliceSprite 是 PixiJS v8 中用于构建可伸缩 UI 元素的专用精灵变体:它将一张纹理划分为 3×3 的九宫格,四个角保持原始大小,四条边分别沿水平/垂直方向拉伸,中心区域双向拉伸,从而让圆角按钮、对话框面板、提示框等边框装饰在任意尺寸下都保持锐利。本文将以仓库内技能文档 nineslice-sprite.md 为主体,结合 NineSliceSprite.ts 与 NineSliceGeometry.ts 源码,完整讲解其构造参数、核心用法、运行时可变属性、默认边框机制,以及从 v7 NineSlicePlane 迁移到 v8 的注意事项,读完即可在项目中直接落地实现响应式 UI。
NineSliceSprite 是什么:九宫格缩放原理
普通 Sprite 的显示尺寸固定等于纹理尺寸,放大必然导致整张图(包括四角装饰)一起模糊变形。NineSliceSprite 把纹理按四条边框切成 9 个区域,改变显示大小时只拉伸中间区域,四角像素始终保持 1:1 采样:
leftWidth rightWidth
+---+--------------------+---+
| 1 | 2 | 3 | topHeight
+---+--------------------+---+
| | | |
| 4 | 5 | 6 |
| | | |
+---+--------------------+---+
| 7 | 8 | 9 | bottomHeight
+---+--------------------+---+
各区域行为(与源码 NineSliceSprite.ts 中的注释完全一致):
- 四角(1、3、7、9):始终不缩放,保持原始像素,圆角与描边不会变形;
- 上下边(2、8):只沿水平方向拉伸;
- 左右边(4、6):只沿垂直方向拉伸;
- 中心(5):水平、垂直双向拉伸。
官方还提供了一页独立的 NineSlice Sprite 文档 描述同一机制。这一技术适用于所有"尺寸需要随内容/窗口变化、但边框装饰必须清晰"的 UI 元素——按钮、面板、对话框、弹窗背景、聊天气泡等。
仓库中的示例资源 panel-031.png 就是专为九宫格准备的 96×96 面板纹理,官方示例 nine-slice-sprite_basic.ts 用它演示了实时拉伸效果,可作为学习与测试的素材。
快速上手
const texture = await Assets.load('panel.png');
const panel = new NineSliceSprite({
texture,
leftWidth: 20,
topHeight: 20,
rightWidth: 20,
bottomHeight: 20,
width: 400,
height: 200,
});
app.stage.addChild(panel);
要点:
- 四个边框值默认都是
10,不传也可; - 拉伸区域由精灵自身的
width/height控制——赋值给 sprite 而不是 texture; - 纹理需先通过
Assets.load加载完成再传入(Assets.load的返回值就是Texture)。
完整可运行版本可参考 nine-slice-sprite_basic.ts:它加载 panel-031.png,设置 30 像素边框与 anchor: 0.5 居中,随后在 ticker 中每帧修改 width / height,即可看到四角保持完整、中心区域跟随拉伸的实时效果:
const bunny = new NineSliceSprite({
texture,
leftWidth: 30,
rightWidth: 30,
topHeight: 30,
bottomHeight: 30,
anchor: 0.5,
x: app.screen.width / 2,
y: app.screen.height / 2,
});
bunny.width = 500;
bunny.height = 300;
app.ticker.add(() => {
counter++;
bunny.width = 500 + (Math.sin(counter / 20) * 100);
bunny.height = 300 + (Math.cos(counter / 20) * 50);
});
构造参数详解:NineSliceSpriteOptions
NineSliceSprite 采用 v8 统一的对象式构造(也兼容直接传入 Texture 的简写形式,见 NineSliceSprite.ts)。完整构造示例:
const panel = new NineSliceSprite({
texture,
leftWidth: 20,
topHeight: 20,
rightWidth: 20,
bottomHeight: 20,
width: 400,
height: 200,
anchor: 0.5,
});
参数表(继承自原文档,默认值已对照源码确认):
| Option | Type | Default | Description |
|---|---|---|---|
texture |
Texture |
Texture.EMPTY |
九宫格的源纹理。 |
leftWidth |
number |
10 |
左侧不缩放边框列的宽度(区域 A)。 |
topHeight |
number |
10 |
顶部不缩放边框行的高度(区域 C)。 |
rightWidth |
number |
10 |
右侧不缩放边框列的宽度(区域 B)。 |
bottomHeight |
number |
10 |
底部不缩放边框行的高度(区域 D)。 |
width |
number |
texture.width(否则 100) |
拉伸后精灵的显示宽度;直接修改顶点而非 UV。 |
height |
number |
texture.height(否则 100) |
拉伸后精灵的显示高度;直接修改顶点而非 UV。 |
anchor |
PointData | number |
0 |
归一化绘制原点,范围 [0, 1]。 |
roundPixels |
boolean |
false |
将渲染坐标取整为整数像素,保证像素风纹理边缘清晰。 |
此外,Container 的所有选项(position、scale、tint、label、filters、zIndex 等)在 NineSliceSprite 上同样有效,完整清单见 constructor-options.md。
默认值的回退链(源码依据)
从 NineSliceSprite.ts 可以看到,边框与尺寸的默认值并不是简单常量,而是一条三级回退链:
this._leftWidth = leftWidth ?? texture?.defaultBorders?.left ?? NineSliceGeometry.defaultOptions.leftWidth;
this._width = width ?? texture.width ?? NineSliceGeometry.defaultOptions.width;
即:显式传入的参数 > 纹理上的 defaultBorders / texture.width > 全局默认值。其中 NineSliceGeometry.defaultOptions 定义于 NineSliceGeometry.ts:四边框默认 10,width / height / originalWidth / originalHeight 默认 100。因此不指定边框时,精灵会自动读取纹理上的 defaultBorders(见下文"纹理级默认边框")。
纹理构造与动态纹理
NineSliceSprite 支持直接传 Texture 对象(内部会包装为 { texture }),也支持在创建后替换纹理(panel.texture = ...)。若纹理是动态更新的(如程序化绘制后频繁修改 UV),需要设置 texture.dynamic = true,精灵才会监听纹理的 update 事件并自动重建顶点(见 NineSliceSprite.ts 的 setter 实现)。
核心用法模式
运行时动态调整尺寸
改变显示尺寸有三种方式,推荐优先使用 setSize:
panel.width = 600;
panel.height = 300;
panel.setSize(600, 300);
const size = panel.getSize();
- 设置
width/height会直接修改精灵顶点,不会缩放底层纹理,四角在任何尺寸下都保持固定大小; setSize(value, height?)是"一次性同时改宽高"的重载对——单独连续设置width和height会触发两次视图更新,而setSize只触发一次,避免重复计算边界;setSize还支持对象形式setSize({ width, height }),以及只传一个数字的等宽高用法(如setSize(200)生成 200×200 正方形),见 NineSliceSprite.ts;getSize(out?)可传入一个可复用的{ width, height }对象来避免每次分配新对象(NineSliceSprite.ts)。
纹理级默认边框:defaultBorders
如果多个面板共用同一张纹理,可以把边框定义在纹理上,一次定义、处处复用:
const texture = new Texture({
source: baseSource,
defaultBorders: { left: 15, top: 15, right: 15, bottom: 15 },
});
const panel = new NineSliceSprite({ texture, width: 400, height: 200 });
defaultBorders是Texture的只读属性(readonly defaultBorders?: TextureBorders,定义见 Texture.ts),在new Texture({...})的构造参数中传入;- 当构造
NineSliceSprite时没有显式传入任何边框值,精灵会自动拾取纹理上的defaultBorders; - 配合精灵图集自动烘焙:加载 spritesheet JSON 时,Spritesheet.ts 会把 JSON 中每个帧的
borders字段(以及anchor)写入生成的Texture,因此通过Assets.load加载的图集纹理天然自带边框信息,new NineSliceSprite({ texture })即可直接使用,无需手工填写边框值。
边框属性运行时可改
四个边框在运行时全部可写,赋值后下一帧渲染会自动重建几何体:
panel.leftWidth = 25;
panel.rightWidth = 25;
panel.topHeight = 15;
panel.bottomHeight = 15;
从源码看,每个 setter 都会调用 onViewUpdate() 标记脏状态(如 NineSliceSprite.ts),渲染管线在下一帧据此重建顶点,无需手动刷新。
读取与还原源纹理尺寸
console.log(panel.originalWidth, panel.originalHeight);
panel.setSize(panel.originalWidth, panel.originalHeight);
originalWidth / originalHeight 是只读 getter,直接返回底层 texture.width / texture.height(NineSliceSprite.ts)。典型用途:把面板还原到源尺寸,或按源尺寸做相对缩放(如 panel.width = panel.originalWidth * 2)。
全局默认值:defaultOptions
NineSliceSprite.defaultOptions.texture = Texture.from('defaultPanel.png');
NineSliceSprite.defaultOptions 是一个可变静态对象,但只有 texture 字段会被作为回退读取(源码中 this.texture = texture ?? NineSliceSprite.defaultOptions.texture)。边框默认值来自 texture.defaultBorders(逐纹理)或 NineSliceGeometry.defaultOptions(全局),尺寸默认值回退到 texture.width / texture.height 或 NineSliceGeometry.defaultOptions.width / .height。设置后新建的、未显式传纹理的精灵将自动使用默认纹理。
像素对齐:roundPixels
const panel = new NineSliceSprite({
texture,
leftWidth: 10,
topHeight: 10,
rightWidth: 10,
bottomHeight: 10,
roundPixels: true,
});
像素风 UI 纹理配合 roundPixels: true 使用,可把渲染坐标吸附到整数像素,避免九宫格切片交界处出现亚像素缝隙。
常见错误与规避
[HIGH] 使用旧的 NineSlicePlane 名称
错误写法:
import { NineSlicePlane } from 'pixi.js';
const panel = new NineSlicePlane(texture, 10, 10, 10, 10);
正确写法:
import { NineSliceSprite } from 'pixi.js';
const panel = new NineSliceSprite({
texture,
leftWidth: 10,
topHeight: 10,
rightWidth: 10,
bottomHeight: 10,
});
NineSlicePlane 在 v8 中已更名为 NineSliceSprite,同时从"位置参数"构造切换为"选项对象"构造。源码 NineSliceSprite.ts 中保留了 NineSlicePlane 作为 NineSliceSprite 的已弃用子类:兼容旧的位置参数签名,但构造时会通过 deprecation 输出警告。新代码一律使用 NineSliceSprite。
[HIGH] 用 scale 缩放面板
错误写法:
panel.scale.set(2);
正确写法:
panel.width = 400;
panel.height = 200;
scale 会把包括四角在内的整个几何体等比放大,四角装饰随之变形,九宫格的意义就没了。调整 NineSliceSprite 尺寸永远使用 width / height(或 setSize),这样只有中心与边缘拉伸、四角保持原样。注意:width / height 修改的是顶点而非 UV,因此也不会出现纹理拉伸模糊。
[MEDIUM] 边框大于纹理尺寸的一半
如果 leftWidth + rightWidth >= texture.width(或 topHeight + bottomHeight >= texture.height),纹理就没有剩余像素留给中心条带,中心区域会被迫用两条边框交界处的"接缝"拉伸填充,而不是纹理中部,视觉效果异常。保持相对边框之和小于对应纹理维度。
顺带一提,NineSliceGeometry.updatePositions() 对"显示尺寸小于边框之和"的情况做了兜底:当 width <= leftWidth + rightWidth 时,会用一个 scale = width / (leftWidth + rightWidth) 的收缩因子按比例压缩边框列,避免顶点顺序翻转(见 NineSliceGeometry.ts)。这是对"面板缩得比边框还小"的保护,但不能替代正确的边框取值。
[MEDIUM] 给精灵添加子节点
NineSliceSprite 与 Sprite、TilingSprite 一样设置了 allowChildren = false(NineSliceSprite.ts),它是场景树的叶子节点,无法承载子对象。需要把九宫格面板与其他内容组合时,用 Container 包裹。
源码级原理:几何体如何被拉伸
NineSliceSprite 的渲染数据由 NineSliceGeometry(继承自 PlaneGeometry)提供,它内部按 verticesX: 4, verticesY: 4 生成 4×4 的顶点网格,即 16 个顶点组成 9 个四边形区域。所有缩放逻辑集中在两个方法:
updatePositions():根据width/height、四边框值以及 anchor 计算每个顶点的位置。左右边框列的 x 坐标分别固定在leftWidth * scale与width - rightWidth * scale,上下边框行同理,四角顶点永远不参与拉伸(NineSliceGeometry.ts);updateUvs():UV 按源纹理尺寸归一化,边框对应的 UV 区间从leftWidth / origW等处切分,保证边框像素始终采样纹理的原始区域(NineSliceGeometry.ts)。
一个值得注意的细节:updateUvs() 会读取纹理的 trim 信息(由 NineSliceSprite.trim 转发,见 NineSliceSprite.ts)。当纹理来自带内边距(padding)的图集且带 trim 数据时,UV 会被钳制到可见像素区域,防止图集中透明 padding 渗入渲染出的四角/边缘。因此从 spritesheet 加载的九宫格纹理可以放心使用,无需额外处理。
结语
NineSliceSprite 是 PixiJS v8 中实现"单张纹理、任意尺寸、边框锐利"UI 的标准方案。掌握四件事即可熟练使用:一是边框值决定哪些像素不缩放(默认 10,也可写在 Texture.defaultBorders 或 spritesheet JSON 中全局复用);二是用 width / height / setSize 而非 scale 调整大小;三是四边框运行时可随时修改,几何体会在下一帧自动重建;四是从 v7 迁移时把 NineSlicePlane 换成 NineSliceSprite 的对象式构造。相关源码与示例集中在 src/scene/sprite-nine-slice、nine-slice-sprite.md 与 examples/nine-slice-sprite_basic.ts,可结合阅读进一步深入。