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

Control.add_theme_color_override

定义

Control.add_theme_color_override 就是用自定义颜色覆盖控件主题中的某个颜色属性。Godot 的 UI 控件使用"主题系统"来管理外观——比如按钮的文字颜色、滑块的颜色等。这个方法让你可以针对单个控件修改颜色，而不影响其他同类控件。

打个比方：主题就像学校统一发的校服（蓝色），add_theme_color_override 就像你偷偷给自己的校服染成了红色——只有你的变了，其他同学的还是蓝色。

在实际游戏开发中，你经常需要让某个按钮变成红色表示危险操作、让某个标签的文字变成绿色表示成功、或者让血条变成黄色表示低血量。

函数签名

C#

public void AddThemeColorOverride(string name, Color color)

GDScript

func add_theme_color_override(name: StringName, color: Color) -> void

参数说明

参数	类型	必需	说明
name	String	是	要覆盖的主题颜色名称，如 "font_color"、"font_hover_color" 等
color	Color	是	新的颜色值，使用 Godot 的 Color 类型

常用颜色名称

名称	适用控件	说明
font_color	Button, Label 等	正常状态的文字颜色
font_hover_color	Button	鼠标悬停时的文字颜色
font_pressed_color	Button	按下时的文字颜色
font_disabled_color	Button	禁用时的文字颜色
font_focus_color	Button	获得焦点时的文字颜色

返回值

无返回值（void）。设置后颜色立即生效。

代码示例

基础用法：修改按钮文字颜色

C#

var dangerButton = GetNode<Button>("DeleteButton");
// 把"删除"按钮的文字变成红色，表示危险操作
dangerButton.AddThemeColorOverride("font_color", new Color(1.0f, 0.2f, 0.2f));
// 运行结果: 按钮文字变成红色

var successLabel = GetNode<Label>("StatusLabel");
successLabel.AddThemeColorOverride("font_color", new Color(0.2f, 0.8f, 0.2f));
// 运行结果: 标签文字变成绿色

GDScript

var danger_button = $DeleteButton as Button
# 把"删除"按钮的文字变成红色，表示危险操作
danger_button.add_theme_color_override("font_color", Color(1.0, 0.2, 0.2))
# 运行结果: 按钮文字变成红色

var success_label = $StatusLabel as Label
success_label.add_theme_color_override("font_color", Color(0.2, 0.8, 0.2))
# 运行结果: 标签文字变成绿色

实际场景：根据血量动态改变血条颜色

C#

using Godot;

public partial class HealthBarUI : Control
{
    private ProgressBar _healthBar;

    public override void _Ready()
    {
        _healthBar = GetNode<ProgressBar>("HealthBar");
    }

    public void UpdateHealth(float current, float max)
    {
        float ratio = current / max;
        _healthBar.Value = ratio * 100;

        // 根据血量比例改变颜色
        Color healthColor;
        if (ratio > 0.6f)
        {
            healthColor = new Color(0.2f, 0.8f, 0.2f); // 绿色：血量充足
        }
        else if (ratio > 0.3f)
        {
            healthColor = new Color(0.9f, 0.7f, 0.1f); // 黄色：血量偏低
        }
        else
        {
            healthColor = new Color(0.9f, 0.15f, 0.15f); // 红色：血量危险
        }

        _healthBar.AddThemeColorOverride("fill_color", healthColor);
        // 运行结果: 血量 > 60% 绿色，30%-60% 黄色，< 30% 红色
    }
}

GDScript

extends Control

@onready var _health_bar: ProgressBar = $HealthBar

func update_health(current: float, max_val: float):
    var ratio = current / max_val
    _health_bar.value = ratio * 100.0

    # 根据血量比例改变颜色
    var health_color: Color
    if ratio > 0.6:
        health_color = Color(0.2, 0.8, 0.2)  # 绿色：血量充足
    elif ratio > 0.3:
        health_color = Color(0.9, 0.7, 0.1)  # 黄色：血量偏低
    else:
        health_color = Color(0.9, 0.15, 0.15) # 红色：血量危险

    _health_bar.add_theme_color_override("fill_color", health_color)
    # 运行结果: 血量 > 60% 绿色，30%-60% 黄色，< 30% 红色

进阶用法：自定义按钮的所有状态颜色

C#

using Godot;

public partial class ThemedButton : Button
{
    [Export] public Color ExNormalColor = new(0.9f, 0.9f, 0.9f);
    [Export] public Color ExHoverColor = new(1.0f, 1.0f, 1.0f);
    [Export] public Color ExPressedColor = new(0.6f, 0.6f, 0.6f);
    [Export] public Color ExDisabledColor = new(0.5f, 0.5f, 0.5f, 0.5f);

    public override void _Ready()
    {
        ApplyCustomColors();
    }

    private void ApplyCustomColors()
    {
        AddThemeColorOverride("font_color", ExNormalColor);
        AddThemeColorOverride("font_hover_color", ExHoverColor);
        AddThemeColorOverride("font_pressed_color", ExPressedColor);
        AddThemeColorOverride("font_disabled_color", ExDisabledColor);
        // 运行结果: 按钮在不同状态下显示不同颜色

        GD.Print("按钮主题颜色已自定义");
    }
}

GDScript

extends Button

@export var normal_color: Color = Color(0.9, 0.9, 0.9)
@export var hover_color: Color = Color(1.0, 1.0, 1.0)
@export var pressed_color: Color = Color(0.6, 0.6, 0.6)
@export var disabled_color: Color = Color(0.5, 0.5, 0.5, 0.5)

func _ready():
    apply_custom_colors()

func apply_custom_colors():
    add_theme_color_override("font_color", normal_color)
    add_theme_color_override("font_hover_color", hover_color)
    add_theme_color_override("font_pressed_color", pressed_color)
    add_theme_color_override("font_disabled_color", disabled_color)
    # 运行结果: 按钮在不同状态下显示不同颜色

    print("按钮主题颜色已自定义")

注意事项

• 只影响当前控件：add_theme_color_override 只修改调用它的那个控件，不会影响其他同类控件。如果想全局修改，应该创建自定义 Theme 资源。
• 颜色名称因控件类型而异：不同控件有不同的可覆盖颜色名称。可以在编辑器中选中控件，查看"Theme Overrides > Colors"部分来找到所有可用的颜色名称。
• 恢复默认值：调用 RemoveThemeColorOverride("font_color") 可以移除覆盖，恢复主题默认颜色。
• Color 的分量范围：Color 的 R、G、B、A 分量都是 0.0 到 1.0 的浮点数，不是 0-255。比如纯红色是 new Color(1, 0, 0) 而不是 new Color(255, 0, 0)。