最后同步日期：2026-04-15 | Godot 官方原文 — ColorRect

ColorRect

节点继承关系

继承链：Node → CanvasItem → Control → ColorRect

Control

类型	名称	说明
属性	Size	控件尺寸
属性	Position	控件位置
属性	AnchorsPreset	锚点预设
属性	GrowDirection	超出容器时的扩展方向
属性	MouseFilter	鼠标事件过滤（停止 / 通过 / 忽略）
属性	FocusMode	焦点模式（无 / 单击 / 全部）
信号	gui_input	接收到 GUI 输入事件
信号	mouse_entered	鼠标进入控件区域
信号	mouse_exited	鼠标离开控件区域
信号	focus_entered	获得焦点
信号	focus_exited	失去焦点
信号	resized	尺寸变化
方法	GrabFocus()	获取焦点
方法	ReleaseFocus()	释放焦点
方法	SetAnchorsPreset()	设置锚点预设
方法	GetMinimumSize()	获取最小尺寸

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

ColorRect 是最简单的 UI 显示节点，就是一个纯色矩形。常用于做半透明遮罩、背景色块、颜色分隔线等。你可以把它想象成一张彩纸——想用什么颜色就填什么颜色，没有文字、没有图片，就是一块纯色。

使用频率：★★★★ 维度专用常用（遮罩、背景色块等常见）

节点用途

• 弹窗的半透明遮罩背景
• UI 区域的纯色背景
• 颜色分隔线或色块

使用场景

• 弹窗后面那层灰蒙蒙的遮罩（半透明黑色 ColorRect）
• UI 区域的纯色背景
• 调试时快速给某个区域上色

常用节点搭配

• 搭配 Control 做遮罩层
• 搭配 Panel 做更复杂的背景

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
color	Color	白色	—	填充颜色（支持透明度，如 new Color(0, 0, 0, 0.5f) 半透明黑）

信号

信号	触发时机	参数
（ColorRect 没有特有信号）	—	—

常用方法

方法	说明
SetColor(Color)	设置填充颜色
GetColor()	获取填充颜色

代码示例

C

using Godot;

public partial class ModalOverlay : Control
{
    public override void _Ready()
    {
        // 创建一个铺满整个父节点的半透明黑色遮罩
        var overlay = new ColorRect();
        overlay.Color = new Color(0, 0, 0, 0.5f);  // 黑色，50% 透明度
        overlay.SetAnchorsPreset(LayoutPreset.FullRect);  // 铺满父节点
        AddChild(overlay);

        // 在遮罩上方放一个提示文字
        var label = new Label();
        label.Text = "这里是弹窗内容";
        label.HorizontalAlignment = HorizontalAlignment.Center;
        label.SetAnchorsPreset(LayoutPreset.Center);
        AddChild(label);
    }
}

GDScript

extends Control

func _ready():
    # 创建一个铺满整个父节点的半透明黑色遮罩
    var overlay = ColorRect.new()
    overlay.color = Color(0, 0, 0, 0.5)  # 黑色，50% 透明度
    overlay.set_anchors_preset(Control.LayoutPreset.FULL_RECT)  # 铺满父节点
    add_child(overlay)

    # 在遮罩上方放一个提示文字
    var label = Label.new()
    label.text = "这里是弹窗内容"
    label.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER
    label.set_anchors_preset(Control.LayoutPreset.CENTER)
    add_child(label)