游戏引擎 / 系统课时
显示第一张 Sprite 图片
显示第一张 Sprite 图片
图片文件进入资源目录后,还需要 SpriteFrame、Sprite 组件、有效尺寸和相机可见性才能显示。本节把一张明确的不透明 PNG 绑定到场景节点,逐项验证从资源到画面的条件。
学习目标
- 区分图片、SpriteFrame 与 Sprite 实例
- 用显式尺寸得到可控的显示结果
- 按资源、节点、相机顺序定位不显示问题
准备素材与显示节点
在 Creator 3.8.8 项目中准备一张自己可使用的 64×64 不透明 PNG,放入 assets/art/player.png。图片内容可以是纯色方块,先不要用大量透明留白的素材。导入后展开图片资源,找到其 SpriteFrame 子资源。
在 Canvas 下创建节点 PlayerIcon,添加 UITransform 和 Sprite。确认节点激活、缩放为 1、颜色透明度不为零。SpriteFrame 是渲染所用的图像区域与相关信息,Sprite 是场景里执行显示的组件;一个资源可供多个不同节点使用。
显式绑定并设置尺寸
把 SpriteBind.ts 挂到 PlayerIcon,将 SpriteFrame 子资源拖到脚本的 frame 字段。这里通过 CUSTOM 模式设定显示宽高,避免把纹理原始尺寸或裁剪结果误当作目标尺寸。
import { _decorator, Component, Sprite, SpriteFrame, UITransform } from 'cc';
const { ccclass, property } = _decorator;
@ccclass('SpriteBind')
export class SpriteBind extends Component {
@property(SpriteFrame)
frame: SpriteFrame | null = null;
start(): void {
const sprite = this.getComponent(Sprite);
const transform = this.getComponent(UITransform);
if (!sprite || !transform || !this.frame) {
console.error('SpriteBind: check Sprite, UITransform and frame');
return;
}
sprite.spriteFrame = this.frame;
sprite.sizeMode = Sprite.SizeMode.CUSTOM;
transform.setContentSize(64, 64); // 显示尺寸独立于素材裁剪
console.log('sprite-size:' + transform.width + 'x' + transform.height);
}
}预期结果:画面中心显示该 PNG,节点显示尺寸为 64×64,日志输出 sprite-size:64x64。复制节点并修改位置后,可看到两个实例共享同一张图片;修改实例位置不会移动图片资源本身。
从最小条件排查透明画面
有尺寸日志但没有图像时,先查看 SpriteFrame 是否正确,再检查 PNG 是否全透明、Sprite 颜色是否透明、父节点是否激活。继续检查节点是否落在相机范围内,以及节点 Layer 是否包含在相机可见集合中。将节点暂时放回 Canvas 中心比同时修改多个参数更容易定位。
图像被拉伸时,检查显示宽高与原图比例;四周留白或中心偏移时,检查素材裁剪、锚点和原始透明边缘。需要九宫格拉伸时使用相应 Sprite 类型与边框设置,不能仅把普通图无限放大后期待边缘保持形状。
先使用未经图集和压缩处理的小素材建立正确基线,再引入生产图集。渲染可见不等于资源管理已经完成;动态加载的资源还需另行管理引用和释放,不能在显示组件仍使用它时随意释放。