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

Control.add_theme_stylebox_override

定义

Control.add_theme_stylebox_override 就是用自定义的样式盒（StyleBox）覆盖控件主题中的某个样式。StyleBox 是 Godot 中用来定义控件外观的"装饰盒"——它定义了背景颜色、边框、圆角、内边距等视觉属性。

打个比方：如果说 add_theme_color_override 是改变文字颜色，那 add_theme_stylebox_override 就是改变整个控件的"外壳"。就像给手机换壳一样——你可以给按钮换上圆角黑底的外壳、给面板换上半透明毛玻璃的外壳。

在实际游戏开发中，StyleBox 覆盖是实现 UI 个性化最常用的方法之一。比如让一个按钮有红色背景表示警告、给面板添加圆角和阴影让它看起来像卡片。

函数签名

C#

public void AddThemeStyleboxOverride(string name, StyleBox stylebox)

GDScript

func add_theme_stylebox_override(name: StringName, stylebox: StyleBox) -> void

参数说明

参数	类型	必需	说明
name	String	是	要覆盖的样式名称，如 "normal"、"hover"、"pressed" 等
stylebox	StyleBox	是	新的样式盒对象，常用 StyleBoxFlat（纯色+边框）或 StyleBoxTexture（贴图背景）

常用样式名称（以 Button 为例）

名称	说明
normal	按钮正常状态的背景
hover	鼠标悬停时的背景
pressed	按下时的背景
disabled	禁用时的背景
focus	获得焦点时的背景

返回值

无返回值（void）。设置后样式立即生效。

代码示例

基础用法：给按钮设置自定义背景

C#

var button = GetNode<Button>("MyButton");

// 创建一个红色圆角的样式盒
var style = new StyleBoxFlat();
style.BgColor = new Color(0.8f, 0.15f, 0.15f);
style.SetCornerRadiusAll(8);
style.SetContentMarginAll(10);

button.AddThemeStyleboxOverride("normal", style);
// 运行结果: 按钮变成红色圆角背景

GDScript

var button = $MyButton as Button

# 创建一个红色圆角的样式盒
var style = StyleBoxFlat.new()
style.bg_color = Color(0.8, 0.15, 0.15)
style.set_corner_radius_all(8)
style.set_content_margin_all(10)

button.add_theme_stylebox_override("normal", style)
# 运行结果: 按钮变成红色圆角背景

实际场景：创建不同状态下的按钮样式

C#

using Godot;

public partial class ActionButton : Button
{
    public override void _Ready()
    {
        // 正常状态：深蓝色圆角
        var normalStyle = new StyleBoxFlat();
        normalStyle.BgColor = new Color(0.15f, 0.3f, 0.6f);
        normalStyle.SetCornerRadiusAll(6);
        normalStyle.SetContentMarginAll(12);
        AddThemeStyleboxOverride("normal", normalStyle);

        // 悬停状态：浅蓝色
        var hoverStyle = new StyleBoxFlat();
        hoverStyle.BgColor = new Color(0.2f, 0.4f, 0.8f);
        hoverStyle.SetCornerRadiusAll(6);
        hoverStyle.SetContentMarginAll(12);
        AddThemeStyleboxOverride("hover", hoverStyle);

        // 按下状态：更深的蓝色
        var pressedStyle = new StyleBoxFlat();
        pressedStyle.BgColor = new Color(0.1f, 0.2f, 0.45f);
        pressedStyle.SetCornerRadiusAll(6);
        pressedStyle.SetContentMarginAll(12);
        AddThemeStyleboxOverride("pressed", pressedStyle);

        // 运行结果: 按钮在正常/悬停/按下时分别显示不同深度的蓝色
    }
}

GDScript

extends Button

func _ready():
    # 正常状态：深蓝色圆角
    var normal_style = StyleBoxFlat.new()
    normal_style.bg_color = Color(0.15, 0.3, 0.6)
    normal_style.set_corner_radius_all(6)
    normal_style.set_content_margin_all(12)
    add_theme_stylebox_override("normal", normal_style)

    # 悬停状态：浅蓝色
    var hover_style = StyleBoxFlat.new()
    hover_style.bg_color = Color(0.2, 0.4, 0.8)
    hover_style.set_corner_radius_all(6)
    hover_style.set_content_margin_all(12)
    add_theme_stylebox_override("hover", hover_style)

    # 按下状态：更深的蓝色
    var pressed_style = StyleBoxFlat.new()
    pressed_style.bg_color = Color(0.1, 0.2, 0.45)
    pressed_style.set_corner_radius_all(6)
    pressed_style.set_content_margin_all(12)
    add_theme_stylebox_override("pressed", pressed_style)

    # 运行结果: 按钮在正常/悬停/按下时分别显示不同深度的蓝色

进阶用法：带边框和阴影的卡片式面板

C#

using Godot;

public partial class CardPanel : PanelContainer
{
    [Export] public Color ExCardColor = new(0.15f, 0.15f, 0.2f, 0.95f);
    [Export] public Color ExBorderColor = new(0.3f, 0.3f, 0.4f);
    [Export] public int ExBorderWidth = 2;
    [Export] public int ExCornerRadius = 12;
    [Export] public int ExShadowSize = 8;

    public override void _Ready()
    {
        var style = new StyleBoxFlat();
        style.BgColor = ExCardColor;
        style.BorderColor = ExBorderColor;
        style.SetBorderWidthAll(ExBorderWidth);
        style.SetCornerRadiusAll(ExCornerRadius);
        style.SetContentMarginAll(16);
        style.ShadowColor = new Color(0, 0, 0, 0.3f);
        style.ShadowSize = ExShadowSize;

        AddThemeStyleboxOverride("panel", style);

        // 运行结果: 面板呈现深色半透明背景、圆角、边框和阴影效果
        GD.Print("卡片面板样式已应用");
    }
}

GDScript

extends PanelContainer

@export var card_color: Color = Color(0.15, 0.15, 0.2, 0.95)
@export var border_color: Color = Color(0.3, 0.3, 0.4)
@export var border_width: int = 2
@export var corner_radius: int = 12
@export var shadow_size: int = 8

func _ready():
    var style = StyleBoxFlat.new()
    style.bg_color = card_color
    style.border_color = border_color
    style.set_border_width_all(border_width)
    style.set_corner_radius_all(corner_radius)
    style.set_content_margin_all(16)
    style.shadow_color = Color(0, 0, 0, 0.3)
    style.shadow_size = shadow_size

    add_theme_stylebox_override("panel", style)

    # 运行结果: 面板呈现深色半透明背景、圆角、边框和阴影效果
    print("卡片面板样式已应用")

注意事项

• StyleBoxFlat 是最常用的子类：StyleBoxFlat 提供了纯色背景、边框、圆角、阴影等功能。如果需要用图片做背景，可以用 StyleBoxTexture。
• 每次调用都会创建新对象：new StyleBoxFlat() 每次都会创建一个新实例。如果多个控件使用相同样式，应该创建一次然后复用。
• 恢复默认样式：调用 RemoveThemeStyleboxOverride("normal") 可以移除覆盖，恢复主题默认样式。
• 样式名称因控件而异：Button 用 "normal"/"hover"/"pressed"，Panel 用 "panel"，LineEdit 用 "normal"/"focus" 等。在编辑器中选中控件，查看 "Theme Overrides > Styleboxes" 来找到所有可用的名称。
• Content Margin 控制内边距：SetContentMarginAll(10) 设置文字与边框之间的距离为 10 像素。如果不设置，文字可能会紧贴边框。