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

ColorPicker

节点继承关系

继承链：Node → CanvasItem → Control → ColorPicker

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()	获取父节点

定义

一个完整的颜色选择面板，可以直接放到界面里。就像 Photoshop 或画图工具里那种有调色板、有 RGB/HSV 滑块的取色器。

使用频率：★★ 偶尔使用（需要让用户选颜色时使用）

节点用途

• 在游戏中让用户自定义颜色
• 画笔/装饰的颜色选择
• 角色衣服颜色自定义

使用场景

• 角色自定义界面的颜色选择
• 地图编辑器的画笔颜色
• 房间装修的颜色选择

常用节点搭配

• 搭配 ColorPickerButton 做弹出式颜色选择
• 搭配 VBoxContainer 排列颜色相关控件

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
color	Color	白色	—	当前选中的颜色
edit_alpha	bool	true	—	是否允许编辑透明度通道
picker_shape	枚举	SV	—	取色器的形状/模式

信号

信号	触发时机	参数
color_changed	颜色变化时	Color 新颜色
preset_added	添加预设颜色时	Color 预设颜色
preset_removed	移除预设颜色时	Color 预设颜色

常用方法

方法	说明
SetColor(Color)	设置当前颜色
GetColor()	获取当前颜色
AddPreset(Color)	添加预设颜色
ClearPresets()	清空预设颜色

代码示例

C

using Godot;

public partial class ColorPickerDemo : Control
{
    public override void _Ready()
    {
        var picker = new ColorPicker();
        picker.Color = new Color(1, 0, 0); // 初始红色
        picker.EditAlpha = false;           // 不需要透明度
        picker.Position = new Vector2(50, 50);

        picker.ColorChanged += (color) =>
        {
            GD.Print($"选中颜色: R={color.R}, G={color.G}, B={color.B}");
        };

        AddChild(picker);
    }
}

GDScript

extends Control

func _ready():
    var picker = ColorPicker.new()
    picker.color = Color(1, 0, 0)  # 初始红色
    picker.edit_alpha = false       # 不需要透明度
    picker.position = Vector2(50, 50)

    picker.color_changed.connect(func(color: Color):
        print("选中颜色: R=" + str(color.r) + ", G=" + str(color.g) + ", B=" + str(color.b))
    )

    add_child(picker)