精灵帧资源(SpriteFrame)

Cocos Creator 的 SpriteFrame 是 UI 渲染基础图形的容器。其本身管理图像的裁剪和九宫格信息,默认持有一个与其同级的 Texture2D 资源引用。

导入精灵帧资源

使用默认的 资源导入 方式将图像资源导入到项目中,然后在 属性检查器 中将图像资源的类型设置为 sprite-frame

set sprite-frame

Creator 便会自动在它下面创建一个如下所示的 spriteFrame 资源:

imported texture

图像资源在 资源管理器 中会以自身图片的缩略图作为图标。在 资源管理器 中选中图像子资源后,属性检查器 下方会显示该图片的缩略图。

spriteFrame 的属性如下:

属性功能说明
Packable是否参与动态合图以及自动图集的构建处理。
Rotated只读属性,不可更改。用于查看 Texture Packer 资源中的子资源是否被旋转
Offset X、Y只读属性,不可更改。用于查看 Texture Packer 资源中矩形框的偏移量
Trim Type裁剪类型,包括:
1. Auto — 自动裁剪(默认),详情请参考 图像资源的自动剪裁
2. Custom — 自定义裁剪
3. None — 无裁剪,使用原图
Trim Threshold透明度阈值,默认为 1,取值范围为 0~1,会将透明度在设定值以下的像素裁减掉。当 Trim Type 设置为 Auto 时生效
Trim X、Y、Width、Height设置裁剪矩形框,当 Trim Type 设置为 Custom 时生效
Border Top、Bottom、Left、Right设置九宫格图边距,可点击下方的 编辑 按钮进行可视化编辑

使用 SpriteFrame

容器内包含对象是贴图的使用方式

在编辑器中,拖拽 SpriteFrame 资源到 Sprite 组件的 Sprite Frame 属性栏中,来切换 Sprite 显示的图像。
在运行时,以上图中的 content 图片为例,整个资源分为三部分:

  • content(图像源资源 ImageAsset)
  • content 的子资源 spriteFrame(精灵帧资源 SpriteFrame)
  • content 的子资源 texture(贴图资源 Texture2D)。

在游戏包内(也就是已经放在 resources 目录下)的资源可以通过:

方法一(加载 SpriteFrame):

  1. const url = 'test_assets/test_atlas/content/spriteFrame';
  2. resources.load(url, SpriteFrame, (err: any, spriteFrame) => {
  3. const sprite = this.getComponent(Sprite);
  4. sprite.spriteFrame = spriteFrame;
  5. });

在服务器上的资源只能加载到图像源 ImageAsset,具体方法请参考 动态加载资源

我们提供了 createWithImage 方法来帮助用户快捷的将 ImageAsset 或者原始图像资源 ImageSource 包装为 SpriteFrame:

方法二(加载 ImageAsset):

  1. const self = this;
  2. const url = 'test_assets/test_atlas/content';
  3. resources.load(url, ImageAsset, (err: any, imageAsset) => {
  4. const sprite = this.getComponent(Sprite);
  5. sprite.spriteFrame = SpriteFrame.createWithImage(imageAsset);
  6. });

或者用户也可以手动填充信息,如下:

  1. const self = this;
  2. const url = 'test_assets/test_atlas/content';
  3. resources.load(url, ImageAsset, (err: any, imageAsset) => {
  4. const sprite = this.getComponent(Sprite);
  5. const spriteFrame = new SpriteFrame();
  6. const tex = new Texture2D();
  7. tex.image = imageAsset;
  8. spriteFrame.texture = tex;
  9. sprite.spriteFrame = spriteFrame;
  10. });

方法三(canvas 绘制内容 UI 上显示)(加载 ImageSource):

  1. const sprite = this.getComponent(Sprite);
  2. sprite.spriteFrame = SpriteFrame.createWithImage(canvas);

或者用户也可以手动填充信息,如下:

  1. const sprite = this.getComponent(Sprite);
  2. const img = new ImageAsset(canvas);
  3. const tex = new Texture2D();
  4. tex.image = img;
  5. const sp = new SpriteFrame();
  6. sp.texture = tex;
  7. sprite.spriteFrame = sp;

容器内包含对象是 RenderTexture 的使用方式

RenderTexture 是一个渲染纹理,它可以将摄像机上的内容直接渲染到一张纹理上而不是屏幕上。SpriteFrame 通过管理 RenderTexture 可以轻松的将 3D 相机内容显示在 UI 上。使用方法如下:

  1. const cameraComp = this.getComponent(Camera);
  2. const renderTexture = new RenderTexture();
  3. const size = view.getVisibleSize();
  4. renderTexture.reset({
  5. width: size.width,
  6. height: size.height,
  7. colorFormat: RenderTexture.PixelFormat.RGBA8888,
  8. depthStencilFormat: RenderTexture.DepthStencilFormat.DEPTH_24_STENCIL_8
  9. });
  10. cameraComp.targetTexture = renderTexture;
  11. const spriteFrame = new SpriteFrame();
  12. spriteFrame.texture = renderTexture;
  13. const sprite = this.getComponent(Sprite);
  14. sprite.spriteFrame = spriteFrame;

API 接口文档:SpriteFrame 资源类型