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

ColorPickerButton

节点继承关系

继承链：Node → CanvasItem → Control → BaseButton → ColorPickerButton

定义

一个按钮，点击后弹出颜色选择面板。和 ColorPicker 的区别是：ColorPicker 是直接把面板放在界面上，而 ColorPickerButton 是点一下才弹出，不占常驻空间。就像很多软件里那个小的"颜色方块"按钮，点一下才弹出取色器。

使用频率：★★ 偶尔使用（需要颜色选择但不想常驻显示时使用）

节点用途

• 紧凑的颜色选择入口
• 设置面板中的颜色选项

使用场景

• 角色自定义中的颜色选择按钮
• 地图编辑器的画笔颜色选择

常用节点搭配

• 搭配 Label 显示颜色名称
• 搭配 HBoxContainer 排列颜色选项

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
color	Color	白色	—	当前选中的颜色
edit_alpha	bool	true	—	弹出的 ColorPicker 是否允许编辑透明度

继承自 BaseButton

属性	类型	默认值	继承自	说明
disabled	bool	false	BaseButton	是否禁用

信号

信号	触发时机	参数
color_changed	颜色变化时	Color 新颜色
pressed	按钮被点击时	无

常用方法

方法	说明
GetPicker()	获取弹出的 ColorPicker 子节点
SetColor(Color)	设置当前颜色
GetColor()	获取当前颜色

代码示例

C

using Godot;

public partial class ColorButtonDemo : Control
{
    public override void _Ready()
    {
        var colorBtn = new ColorPickerButton();
        colorBtn.Color = new Color(0, 1, 0); // 初始绿色
        colorBtn.EditAlpha = false;
        colorBtn.Position = new Vector2(100, 100);

        colorBtn.ColorChanged += (color) =>
        {
            GD.Print($"选择了颜色: {color}");
        };

        AddChild(colorBtn);
    }
}

GDScript

extends Control

func _ready():
    var color_btn = ColorPickerButton.new()
    color_btn.color = Color(0, 1, 0)  # 初始绿色
    color_btn.edit_alpha = false
    color_btn.position = Vector2(100, 100)

    color_btn.color_changed.connect(func(color: Color):
        print("选择了颜色: " + str(color))
    )

    add_child(color_btn)