CocosCreator3.8研究笔记（十六）CocosCreator 2D对象

CocosCreator 中，不涉及模型的图片渲染体统称为 2D 渲染对象。

所有的 2D渲染对象需在 RenderRoot 节点下（带有 RenderRoot2D 组件的节点）才可以被渲染，由于 Canvas 组件本身继承 RenderRoot2D 组件，所以 Canvas 组件一般作为数据收集的入口。

2D 对象大致可以分为两类，2D 渲染对象 和 用户界面 User-interface（UI）。

区别在于 2D 渲染对象一般只负责将 2D 对象渲染出来，而 UI 则更多的承担着用户交互的能力。

一、2D 渲染组件

本身拥有渲染能力的组件我们称为 2D 渲染组件。

常用的 2D 渲染组件：Sprite 组件、Label 组件、Mask 组件、Graphics 组件、RichText 组件、UIStaticBatch 组件、Spine骨骼动画。

1、Sprite 组件

Sprite（精灵）是 2D 游戏最常见的显示图像的方式，在节点上添加 Sprite 组件，就可以在场景中显示项目资源中的图片。

（1）、Sprite 属性

属性	功能说明
Type	渲染模式，包括普通（Simple）、九宫格（Sliced）、平铺（Tiled）和填充（Filled）四种模式，详情请参考下文 渲染模式 部分的内容
CustomMaterial	自定义材质
Grayscale	灰度模式，开启后 Sprite 会使用灰度模式渲染。
Color	图片颜色
Sprite Atlas	Sprite 显示图片资源所属的图集
Sprite Frame	渲染 Sprite 使用的 SpriteFrame 图片资源
Size Mode	指定 Sprite 的尺寸 Trimmed 表示会使用原始图片资源裁剪透明像素后的尺寸 Raw 表示会使用原始图片未经裁剪的尺寸 Custom 表示会使用自定义尺寸。当用户手动修改过 Size 属性后，Size Mode 会被自动设置为 Custom，除非再次指定为前两种尺寸。
Trim	是否渲染原始图像周围的透明像素区域

（2）、渲染模式

• 普通模式（Simple）：根据原始图片资源渲染 Sprite，在这个模式下，我们一般不会手动修改节点的尺寸，保证场景中显示的图像和原始图片比例一致。
  
  
• 九宫格模式（Sliced）：图像将被分割成九宫格，并按照一定规则进行缩放以适应可随意设置的尺寸(size)。通常用于 UI 元素，或将可以无限放大而不影响图像质量的图片制作成九宫格图来节省游戏资源空间。
  
  
• 平铺模式（Tiled）：当 Sprite 的尺寸增大时，图像不会被拉伸，而是会按照原始图片的大小不断重复，就像平铺瓦片一样将原始图片铺满整个 Sprite 规定的大小。
  
  
• 填充模式（Filled）：根据原点和填充模式的设置，按照一定的方向和比例绘制原始图片的一部分。经常用于进度条的动态展示。

填充模式（Filled）

Type 属性选择填充模式后，会出现一组新的属性可供配置：

属性	功能说明
Fill Type	填充类型选择，有 HORIZONTAL（横向填充）、VERTICAL（纵向填充）和 RADIAL（扇形填充）三种。
Fill Start	填充起始位置的标准化数值（从 0 ~ 1，表示填充总量的百分比），选择横向填充时，Fill Start 设为 0，就会从图像最左边开始填充
Fill Range	填充范围的标准化数值（同样从 0 ~ 1），设为 1，就会填充最多整个原始图像的范围。
Fill Center	填充中心点，该属性只有选择了 RADIAL 填充类型才能修改。决定了扇形填充时会环绕 Sprite 上的哪个点。

填充模式注意事项：

• 在 HORIZONTAL 和 VERTICAL 这两种填充类型下，Fill Start 设置的数值将影响填充总量，如果 Fill Start 设为 0.5，那么即使 Fill Range 设为 1.0，实际填充的范围也仍然只有 Sprite 总大小的一半。

  
  

• 而 RADIAL 类型中 Fill Start 只决定开始填充的方向，Fill Start 为 0 时，从 x 轴正方向开始填充。Fill Range 决定填充总量，值为 1 时将填充整个圆形。Fill Range 为正值时逆时针填充，为负值时顺时针填充。

2、Label 组件

Label 组件用来显示一段文字，文字可以是系统字体，TrueType 字体、BMFont 字体或艺术数字。

（1）、Label 属性

属性	功能说明
CustomMaterial	自定义材质
Color	文字颜色
String	文本内容字符串
HorizontalAlign	文本的水平对齐方式。可选值有 LEFT、CENTER 和 RIGHT
VerticalAlign	文本的垂直对齐方式。可选值有 TOP、CENTER 和 BOTTOM
FontSize	文本字体大小
FontFamily	文字字体名字，在使用系统字体时生效
LineHeight	文本的行高
Overflow	文本的排版方式，目前支持 CLAMP、SHRINK 和 RESIZE_HEIGHT
EnableWrapText	是否开启文本换行（在排版方式设为 CLAMP、SHRINK 时生效）
Font	指定文本渲染需要的字体资源
UseSystemFont	布尔值，是否使用系统字体
CacheMode	文本缓存类型，仅对 系统字体 或 TTF 字体有效，BMFont 字体无需进行这个优化。包括 NONE、BITMAP、CHAR 三种模式
IsBold	文字是否加粗，支持系统字体以及部分 TTF 字体
IsItalic	文字是否倾斜，支持系统字体以及 TTF 字体
IsUnderline	文字是否加下划线，支持系统字以及 TTF 字体

（2）、Label 排版

属性	功能说明
CLAMP	文字尺寸不会根据 Content Size 的大小进行缩放。 Wrap Text 关闭的情况下，按照正常文字排列，超出 Content Size 的部分将不会显示。 Wrap Text 开启的情况下，会试图将本行超出范围的文字换行到下一行。如果纵向空间也不够时，也会隐藏无法完整显示的文字。
SHRINK	文字尺寸会根据 Content Size 大小进行自动缩放（不会自动放大，最大显示 Font Size 规定的尺寸）。 Wrap Text 开启时，当宽度不足时会优先将文字换到下一行，如果换行后还无法完整显示，则会将文字进行自动适配 Content Size 的大小。 Wrap Text 关闭时，则直接按照当前文字进行排版，如果超出边界则会进行自动缩放。
RESIZE_HEIGHT	文本的 Content Size 会根据文字排版进行适配，这个状态下用户无法手动修改文本的高度，文本的高度由内部算法自动计算出来。

3、Mask 遮罩组件

Mask 用于规定子节点可渲染的范围，默认带有 Mask 组件的节点会使用该节点的约束框（也就是 属性检查器 中 Node 组件的 ContentSize 规定的范围）创建一个矩形渲染遮罩，该节点的所有子节点都会依据这个遮罩进行裁剪，遮罩范围外的将不会渲染。

（1）、Mask 属性

属性	功能说明
Type	遮罩类型，包括 GRAPHICS_RECT、GRAPHICS_ELLIPSE、GRAPHICS_STENCIL、SPRITE_STENCIL 四种类型
Segments	椭圆遮罩的曲线细分数，只在遮罩类型设为 ELLIPSE 时生效
Inverted	反向遮罩

（2）、Type 类型

• GRAPHICS_RECT 矩形遮罩

• GRAPHICS_ELLIPSE 圆形遮罩

也可动态设置GRAPHICS_ELLIPSE:

const mask = this.getComponent(Mask);
mask.type = Mask.Type.ELLIPSE;
mask.segments = 32;

• GRAPHICS_STENCIL 自定义图形遮罩

代码动态设置GRAPHICS_ELLIPSE:

const g = this.mask.node.getComponent(Graphics);
g.lineWidth = 10;
g.fillColor.fromHEX('#ff0000');
g.moveTo(-10, 0);
g.lineTo(0, -20);
g.lineTo(30, 0);
g.lineTo(0, 40);
g.close();
g.stroke();
g.fill();

• SPRITE_STENCIL 自定义图片遮罩

const mask = this.getComponent(Mask);
mask.type = Mask.Type.SPRITE_STENCIL;
const sprite = this.getComponent(Sprite);
sprite.spriteFrame = this.stencilSprite;
mask.alphaThreshold = 0.1;

（3)、Mask 遮罩使用注意事项

• 节点添加了 Mask 组件之后，所有在该节点下的子节点，在渲染的时候都会受 Mask 影响。
• GRAPHICS_STENCIL 类型在这里没有做任何引擎需要的事，只是放开了对 graphics 操控，用户可以使用 mask 组件里的 graphics 属性来绘制自定义图形，但是节点的点击事件还是根据节点的尺寸来计算。
• SPRITE_STENCIL 类型默认需要一个图片资源，如果没有设置的话，相当于没有遮罩。

4、Graphics 组件

Graphics 组件提供了一系列绘画接口：

方法	功能说明
moveTo (x, y)	把路径移动到画布中的指定点，不创建线条
lineTo (x, y)	添加一个新点，然后在画布中创建从该点到最后指定点的线条
bezierCurveTo (c1x, c1y, c2x, c2y, x, y)	创建三次方贝塞尔曲线
quadraticCurveTo (cx, cy, x, y)	创建二次贝塞尔曲线
arc (cx, cy, r, startAngle, endAngle, counterclockwise)	创建弧/曲线（用于创建圆形或部分圆）
ellipse (cx, cy, rx, ry)	创建椭圆
circle (cx, cy, r)	创建圆形
rect (x, y, w, h)	创建矩形
close ()	创建从当前点回到起始点的路径
stroke ()	绘制已定义的路径
fill ()	填充当前绘图（路径）
clear ()	清除所有路径

（1）、Graphics 组件属性

属性	功能说明
CustomMaterial	自定义材质，可用于实现溶解、外发光等渲染效果。
LineWidth	设置或返回当前的线条宽度
LineJoin	设置或返回两条线相交时，所创建的拐角类型
LineCap	设置或返回线条的结束端点样式
StrokeColor	设置或返回笔触的颜色
FillColor	设置或返回填充绘画的颜色
MiterLimit	设置或返回最大斜接长度

（2）、绘图方法演示

import { _decorator, Component, Graphics } from 'cc';
const { ccclass, property } = _decorator;
@ccclass('Test')
export class Test extends Component {
    start () {
        const g = this.getComponent(Graphics);
        g.lineWidth = 1;
        g.fillColor.fromHEX('#ff0000');
        g.moveTo(-20, 0);
        g.lineTo(0, -60);
        g.lineTo(20, 0);
        g.lineTo(0, 60);
        g.close();
        g.stroke();
        g.fill();
    }
}