Cocos Creator Graphics 组件用法详解

Graphics（图形）组件是 Cocos Creator 提供的一个强大的 2D 绘图工具，它允许你在节点上动态绘制各种矢量图形，如线条、矩形、圆形、多边形等。Graphics 非常适合用于创建自定义 UI 元素、绘制游戏背景、实现特效或调试可视化。

一、什么是 Graphics 组件？

Graphics 组件基于 Canvas 2D 绘图 API 设计，但它是由引擎底层实现的，性能优于 HTML5 Canvas，并且与 Cocos Creator 的坐标系和渲染管线无缝集成。你可以将它附加到任何节点上，然后通过脚本调用绘图方法，在该节点的本地坐标系中绘制图形。

二、添加 Graphics 组件

在代码中为节点添加 Graphics 组件：

import { _decorator, Component, Node, Graphics } from 'cc';

@ccclass('MyGraphics')
export class MyGraphics extends Component {
    start() {
        // 为当前节点添加 Graphics 组件（如果还没有）
        let graphics = this.getComponent(Graphics);
        if (!graphics) {
            graphics = this.addComponent(Graphics);
        }

        // 开始绘图...
        this.drawSomething(graphics);
    }

    drawSomething(graphics: Graphics) {
        // 绘制代码
    }
}

也可以在编辑器中选择节点，通过“添加组件”按钮搜索“Graphics”来添加。

三、基本绘图流程

Graphics 的绘图通常遵循以下步骤：

获取 Graphics 组件：通过 getComponent(Graphics) 或 addComponent(Graphics)。
设置样式（可选）：如线条颜色、填充颜色、线宽等。
开始路径：使用 moveTo 或直接调用形状方法（如 rect、circle）。
绘制路径：使用 lineTo、bezierCurveTo 等添加线段。
描边或填充：调用 stroke() 或 fill() 来实际渲染路径。
清除（可选）：需要重新绘制时调用 clear()。

四、常用绘图 API

样式设置

方法	描述
`lineWidth`(属性)	设置或获取线条宽度（像素）。
`strokeColor`(属性)	设置或获取描边颜色（Color 对象）。
`fillColor`(属性)	设置或获取填充颜色（Color 对象）。
`setLineWidth(width)`	设置线宽。
`setStrokeColor(color)`	设置描边颜色。
`setFillColor(color)`	设置填充颜色。
`setColor(color)`	同时设置描边和填充颜色。

路径绘制

方法	描述
`moveTo(x, y)`	将路径起点移动到指定坐标。
`lineTo(x, y)`	从当前点绘制直线到指定点。
`bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)`	绘制三次贝塞尔曲线。
`quadraticCurveTo(cpx, cpy, x, y)`	绘制二次贝塞尔曲线。
`arc(cx, cy, r, startAngle, endAngle, counterclockwise?)`	绘制圆弧（角度为弧度）。
`circle(cx, cy, r)`	绘制圆（快捷方式，相当于调用 `arc`）。
`ellipse(cx, cy, rx, ry)`	绘制椭圆。
`rect(x, y, w, h)`	绘制矩形。
`roundRect(x, y, w, h, r)`	绘制圆角矩形。
`clear()`	清除所有绘图内容。

渲染控制

方法	描述
`stroke()`	根据当前路径描边。
`fill()`	填充当前路径。
`closePath()`	闭合当前路径（连接当前点到起点）。

注意：所有绘图操作都是累积的，每次调用 stroke() 或 fill() 都会基于之前定义的路径进行渲染，除非你调用 clear() 清除。

五、完整示例

示例1：绘制一个红色的圆

import { _decorator, Component, Graphics, Color } from 'cc';

@ccclass('DrawCircle')
export class DrawCircle extends Component {
    start() {
        const g = this.getComponent(Graphics);
        if (!g) return;

        // 设置填充颜色为红色
        g.fillColor = Color.RED;
        // 画一个圆心在 (0,0)，半径 50 的圆
        g.circle(0, 0, 50);
        g.fill(); // 填充圆

        // 也可以设置描边
        g.strokeColor = Color.BLACK;
        g.lineWidth = 2;
        g.stroke(); // 描边
    }
}

示例2：绘制一个带边框的矩形

drawRect(g: Graphics) {
    g.clear(); // 先清除之前的内容

    // 设置填充色为半透明蓝色
    g.fillColor = new Color(0, 0, 255, 128);
    g.fillRect(-100, -50, 200, 100); // fillRect 是 rect + fill 的快捷方式

    // 设置描边为黑色，线宽 3
    g.strokeColor = Color.BLACK;
    g.lineWidth = 3;
    g.rect(-100, -50, 200, 100); // 定义矩形路径
    g.stroke();
}

示例3：绘制一条折线

drawPolyline(g: Graphics) {
    g.lineWidth = 2;
    g.strokeColor = Color.GREEN;

    g.moveTo(0, 0);
    g.lineTo(50, 100);
    g.lineTo(100, 50);
    g.lineTo(150, 150);
    g.stroke();
}

六、坐标系统

Graphics 的绘图坐标是相对于节点自身的本地坐标系。也就是说：

原点 (0,0) 是节点的锚点位置。
如果你希望图形出现在节点中心，就以 (0,0) 为中心绘制。
节点本身的变换（位置、旋转、缩放）会影响最终图形在屏幕上的显示。

例如，如果你希望 Graphics 绘制的图形填满整个节点，可以基于节点的 UITransform 尺寸来绘制：

const uiTransform = this.getComponent(UITransform);
const w = uiTransform.width;
const h = uiTransform.height;
g.rect(-w/2, -h/2, w, h); // 如果锚点在中心

七、性能与注意事项

避免频繁清除和重绘：如果每帧都调用 clear() 和重新绘制，会增加 CPU 负载。适合静态图形或偶尔更新的场景。
使用缓存：如果图形复杂且变化少，可以绘制到纹理（RenderTexture）来提高性能。
路径数量：过多的路径点会影响渲染性能，尽量简化路径。
透明度：设置颜色时包含 Alpha 通道可实现透明效果。
在 update 中绘制：通常不推荐，除非图形需要每帧动态变化（如绘制波形、进度条）。此时应调用 clear() 然后重新绘制。
组件销毁：当节点销毁时，Graphics 组件也会自动清理，无需手动释放。

八、实际应用场景

绘制自定义 UI 元素：如进度条、技能冷却圈、瞄准线。
调试可视化：显示碰撞盒、路径点、区域范围。
游戏背景网格：绘制网格或坐标轴。
特效：如激光、闪电链、弹道轨迹。
编辑器工具：制作自定义的辅助工具。

示例：绘制网格背景

drawGrid(g: Graphics, gridSize: number, count: number) {
    g.strokeColor = Color.GRAY;
    g.lineWidth = 1;

    const total = gridSize * count;
    for (let i = -count; i <= count; i++) {
        const pos = i * gridSize;
        g.moveTo(-total, pos);
        g.lineTo(total, pos);
        g.moveTo(pos, -total);
        g.lineTo(pos, total);
    }
    g.stroke();
}