PixiJS v8 NineSliceSprite 实战指南:九宫格缩放实现任意尺寸不失真的 UI 面板与按钮

原创2026-09-18 10:20:041,964 阅读
文章标签:前端图形学游戏开发WebAssembly

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,可结合阅读进一步深入。

登录后查看全文
pixijs