Godot UI布局指南

UI 布局主要依赖 Control 节点体系 + 容器（Container）+ 锚点（Anchor）

布局组件

Container（自动布局的关键）

容器	用途
HBoxContainer	横向排列
VBoxContainer	纵向排列
GridContainer	网格
MarginContainer	内边距
CenterContainer	居中
PanelContainer	带背景
...	其它

Container 组件结合组件设置，控制设置的方位（上，下，左，右，居中），设置是收缩还是撑满容器。

锚点（Anchor）定位布局

在 Godot 中，非常核心的规则：“父节点的属性决定了子节点的行为。”
简单一句话总结：如果父节点是容器（Container），子节点的锚点（Anchors）就会失效。
可以使用进行定位布局，可直接使用锚点预设，也可以自定义：

在使用自定义时：

Anchors Points（锚点）：百分比定位

锚点的值通常在 $0.0$ 到 $1.0$ 之间。它定义了节点四个边缘（左、上、右、下）相对于父级容器尺寸的比例。

• 0.0： 父级的最左侧或最顶端。
• 0.5： 父级的正中间。
• 1.0： 父级的最右侧或最底端。

Anchors Offsets（偏移）：像素微调

偏移量是基于锚点位置的像素加减。

• 如果 Anchor Left 是 $0.5$（中心），而 Offset Left 是 $20$：
  • 那么该节点的左边界将位于：父容器中心点 + 20 像素的位置。
• 如果 Anchor Right 是 $1$（最右），而 Offset Right 是 $-50$：
  • 那么该节点的右边界将位于：距离父容器最右侧缩进 50 像素的位置。

内容组件

基础 UI 内容控件

文本类

节点	说明
Label	显示静态文本
RichTextLabel	富文本（颜色、图片、BBCode）
LineEdit	单行文本输入
TextEdit	多行文本输入

按钮类

节点	说明
Button	普通按钮
CheckBox	复选框
CheckButton	开关式按钮
OptionButton	下拉选择框
MenuButton	带弹出菜单的按钮
LinkButton	超链接样式按钮

图像 / 显示类

节点	说明
TextureRect	显示图片
NinePatchRect	九宫格拉伸背景
ColorRect	纯色矩形（遮罩、背景）
VideoStreamPlayer	播放视频（UI 中可用）

进度 / 数值显示控件

常用于：血条、加载条、音量调节

节点	说明
ProgressBar	进度条
TextureProgressBar	自定义贴图进度条
SpinBox	数值输入（带加减）
HSlider / VSlider	滑动条
HScrollBar / VScrollBar	滚动条

窗口 / 面板类

节点	说明
Panel	普通面板
Window	独立窗口（Godot 4 新强化）
Popup	弹出窗口基类
PopupPanel	面板弹窗
AcceptDialog	确认弹窗
ConfirmationDialog	确认/取消弹窗
FileDialog	文件选择
ColorPicker / ColorPickerButton	颜色选择器

Panel = 有背景、有边框、可被 Theme 控制的 UI 容器/背景控件
常见用途：设置面板，弹窗底板，HUD 背景，卡片
Panel 会使用 Theme 中的 StyleBoxTexture 来绘制背景和边框：

• 背景色 / 背景贴图
• 边框宽度、颜色、圆角
• 可统一由 Theme 控制
• 不会自动排列子节点，不会处理间距、对齐
• 可在其内添加布局容器节点进行布局处理，或者使用PanelContainer

可以在统一在主题中设置新的Panel类型进行类样式设置，也可直接在面板中的“主题覆盖” 使用新的“StyleBoxTexture” 来设置“AtlasTexture”, 设置“AtlasTexture” 在 “Sub-Region”编辑子区域即可。

关于Panel的大小，Panel 只有在“有尺寸（rect）”时才会绘制背景，Panel 不会自己产生尺寸，所以就只有两条路：
1️⃣ 被父容器撑开（推荐）
2️⃣ 你手动给它一个大小

列表 / 数据展示类

节点	说明
ItemList	简单列表
Tree	树形结构
TabBar	标签栏
OptionButton	轻量下拉列表

交互 & 辅助控件

节点	说明
TooltipLabel	提示信息
TextureButton	使用贴图的按钮
TouchScreenButton	触屏按钮
Control	所有 UI 的基类
CanvasLayer	UI 层级管理（HUD 常用）

容器大小

Godot 的 UI（Control / Container）容器的大小一般来说只可能来自这三种来源之一：
1️⃣ 父节点给它分配的空间（最常见）
2️⃣ 自身的 anchors / offsets（手动或预设）
3️⃣ Container 根据规则“计算并分配”子节点大小（反向是少数特例）

在 Godot UI 中：

🔽 父 → 子：可以控制大小
🔼 子 → 父：几乎不影响大小

这是和 Web（HTML）思维完全不同的地方。

容器分情况

size = (0, 0)的容器

普通 Control（包括 Panel），若不设置大小则：

• 默认 size = (0, 0)
• 不会因为子节点存在而变大
• 不会继承父节点 size

👉 结果：

• Button 能显示（它自己有 size）
• Panel 背景看不到（size 为 0）

✅ Control / Panel = 必须被撑开或手动设大小

Container（VBox / HBox / Grid 等）

Container 的核心规则

Container 自己的大小：来自父节点

Container 只负责：给子节点分配大小

唯一的“子 → 父”影响（例外）

🔹 Minimum Size（最小尺寸）

有些 Control 会提供 最小尺寸建议：

• Label（文字尺寸）
• Button（文本 + padding）
• TextureRect（图片大小）
• Panel

只有在以下情况下才生效：

• 父节点是 Container
• 父节点在计算布局时参考 min_size
  ⚠️ 但依然不会反向改变父 Container 的 size

编写主题

与网页开发的 CSS 不同，Godot 使用的是一套基于 Theme（主题） 和 StyleBox（样式盒） 的系统。
可以使用以下三种主要方式来编写或配置样式：

1. 使用主题编辑器 (推荐方式)

这是最常用且最高效的方法。通过创建一个 Theme 资源，你可以全局性地定义按钮、标签等控件的外观。

• 创建主题：在文件系统中右键 -> 新建资源 -> Theme。
• 编辑样式盒 (StyleBox)：
  • StyleBoxFlat：用于创建纯色、圆角、边框和阴影的效果（最常用）。
  • StyleBoxTexture：使用图片作为背景（支持九宫格拉伸，类似 CSS 的 border-image）。
• 类型变体 (Type Variations)：如果你想让工具栏的某些按钮变红（如“删除”按钮），而其他按钮保持默认，可以在主题中创建一个 ToolButton 的变体。设置基础类型后就可对默认的样进行编辑了。
• 应用主题：要使用特定类型的主题变体只需要在检查器主题中的“Type Variation”中进行设置（gd 4.6之前要手动填写， 4.6 有时能自动读取，有时抽风读取不了创建的主题变体）。
  

2. 局部覆盖 (Theme Overrides)

如果你只想修改某一个特定节点的样式，而不想影响全局，可以在该节点的“检查器 (Inspector)”面板中找到 Theme Overrides。

• 在这里你可以直接更改字体大小、颜色或替换它的 StyleBox。
• 注意：过度使用局部覆盖会导致 UI 难以维护。建议尽量通过全局 Theme 处理。

3. 使用 GDScript 代码编写样式

如果你需要根据游戏逻辑动态改变样式，可以使用代码。

修改基本属性

# 修改颜色
$Label.add_theme_color_override("font_color", Color.RED)

# 修改字体大小
$Label.add_theme_font_size_override("font_size", 32)

动态创建 StyleBox

如果你想从头用代码写一个圆角矩形背景：

func _ready():
    var style = StyleBoxFlat.new()
    style.bg_color = Color(0.2, 0.6, 1.0) # 天蓝色
    style.set_corner_radius_all(10)      # 设置圆角
    style.border_width_left = 2          # 设置边框
    
    # 应用到按钮的 "normal" 状态
    $Button.add_theme_stylebox_override("normal", style)