#Godot 4 常用 UI 节点详解

在 Godot 4 中，UI 系统基于 Control（控件） 节点构建。所有 UI 节点都继承自 Control，形成一棵完整的 UI 树。与游戏引擎中常见的"Canvas + DOM"模式不同，Godot 的 UI 系统是声明式的——你在场景中搭好节点树，引擎自动完成布局计算。

#一、布局系统：Container 家族

Container 是 Godot UI 的骨架。它决定了子节点的大小和位置。理解 Container 是理解整个 UI 系统的第一步。

#1.1 MarginContainer

用途：给子节点四周留出固定的内边距。

核心属性：

• theme_override_constants/margin_left：左边距像素
• theme_override_constants/margin_top：上边距
• theme_override_constants/margin_right：右边距
• theme_override_constants/margin_bottom：下边距

类比前端：相当于 padding，但它是一个独立的节点，而不是某个节点的属性。

典型用法：给整个面板留一圈呼吸空间。比如一个对话框，外层用 MarginContainer 保证内容不会紧贴屏幕边缘。

#1.2 HBoxContainer

用途：子节点水平排列，一行排到底。

核心属性：

• separation：子节点之间的间距
• alignment：对齐方式（左、中、右）
• add_spacer(beginning)：在首尾插入弹性空白

类比前端：display: flex; flex-direction: row;

典型用法：底部工具栏（一排图标按钮）、对话框底部的"确定/取消"按钮组。

#1.3 VBoxContainer

用途：子节点垂直排列，从上往下堆叠。

核心属性：与 HBoxContainer 对称，只是方向不同。

类比前端：display: flex; flex-direction: column;

典型用法：设置菜单（一行一行的选项）、物品列表、对话框内容区域。

#1.4 GridContainer

用途：子节点按网格排列，自动换行。

核心属性：

• columns：列数
• h_separation / v_separation：水平/垂直间距

类比前端：display: grid; grid-template-columns: repeat(N, 1fr);

典型用法：背包格子、技能图标网格、装备栏。

#1.5 FlowContainer（HFlowContainer / VFlowContainer）

用途：子节点按顺序排列，空间不够时自动换行。比 GridContainer 更灵活——不需要固定列数。

类比前端：display: flex; flex-wrap: wrap;

典型用法：标签云、技能列表、动态数量的图标排列。

#1.6 CenterContainer

用途：让子节点在容器内居中显示。

核心属性：

• use_top_left：是否从左上角开始（默认居中）

类比前端：display: flex; justify-content: center; align-items: center;

典型用法：启动画面居中 Logo、弹窗居中。

#1.7 SubViewportContainer

用途：在 UI 中嵌入一个 3D 视口（Viewport），可以渲染 3D 场景作为 UI 的一部分。

类比前端：类似一个 <iframe>，但渲染的是 Godot 场景而非网页。

典型用法：角色预览窗口（旋转 3D 模型）、小地图、装备预览。

#二、基础控件：Label、Button、TextureRect

#2.1 Label

用途：显示文本。

核心属性：

• text：文本内容
• horizontal_alignment / vertical_alignment：对齐方式
• autowrap_mode：自动换行模式
• max_lines_visible：最大可见行数
• visible_characters：逐字显示效果（配合动画）

进阶用法：

• BBCode 支持：启用 bbcode_enabled 后，可以写 <b>粗体</b>、<i>斜体</i>、[color=red]红色文字[/color] 等富文本效果
• 动态打字机效果：用 visible_characters 配合 Timer 逐个显示字符

类比前端：<p> 或 <span>，但功能更丰富。

#2.2 RichTextLabel

用途：支持富文本、图片嵌入、滚动的高级文本控件。

核心属性：

• bbcode_enabled：启用 BBCode
• scroll_active：是否可滚动
• fit_content：内容自适应高度

比 Label 强在哪：

• 支持内嵌图片（[img] 标签）
• 支持可点击的超链接
• 支持表格
• 可以动态追加文本（append_text()）

典型用法：聊天窗口、任务日志、物品描述（带图标）。

#2.3 Button

用途：可点击的按钮。

核心属性：

• text：按钮文字
• icon：按钮图标
• flat：去边框（扁平风格）
• toggle_mode：切换模式（按下弹起，类似开关）
• button_group：按钮组（单选效果）

信号：

• pressed()：点击时触发
• toggled(button_pressed)：切换状态变化时触发

类比前端：<button>，Godot 还提供了几个变体：

#2.4 Button 家族变体

节点类型	用途	类比
CheckBox	带勾选框的按钮	<input type="checkbox">
CheckButton	开关切换按钮	Toggle Switch
LinkButton	无边框的可点击链接	<a>
MenuButton	点击弹出下拉菜单	Dropdown
OptionButton	下拉选择框	<select>
ColorPickerButton	点击弹出颜色选择器	<input type="color">
TextureButton	用纹理图片当按钮	图片按钮

#三、输入控件：LineEdit、TextEdit、SpinBox

#3.1 LineEdit

用途：单行文本输入框。

核心属性：

• text：当前文本
• placeholder_text：占位提示文字
• secret：密码模式（显示星号）
• max_length：最大字符数
• clear_button_enabled：显示清除按钮
• editable：是否可编辑

信号：

• text_changed(new_text)：内容变化时触发
• text_submitted(new_text)：按回车时触发
• focus_entered() / focus_exited()：焦点获取/失去

类比前端：<input type="text">

#3.2 TextEdit

用途：多行文本编辑器。

核心属性：

• text：文本内容
• wrap_mode：换行模式
• syntax_highlighting：语法高亮（可做简单代码编辑器）
• readonly：只读模式

典型用法：日志输出、代码编辑器、多行聊天输入。

#3.3 SpinBox

用途：带上下箭头的数字输入框。

核心属性：

• value：当前数值
• min_value / max_value：范围
• step：步进值
• prefix / suffix：前后缀文字（如"级"、"秒"）

类比前端：<input type="number">，但自带好看步进按钮。

#四、显示类控件

#4.1 TextureRect

用途：显示纹理图片。

核心属性：

• texture：图片纹理
• stretch_mode：拉伸模式
  • Scale：按比例缩放
  • Tile：平铺
  • Keep Aspect Centered：保持比例居中
• expand_mode：扩展模式

典型用法：头像、物品图标、背景图、血条图片。

#4.2 ProgressBar

用途：进度条。

核心属性：

• value：当前值
• min_value / max_value：范围
• show_percentage：是否显示百分比数字

典型用法：血量条、经验值条、加载进度。

#4.3 TextureProgressBar

用途：用纹理做进度条（更美观）。

核心属性：

• texture_progress：进度条纹理
• texture_under：底图纹理（未填充部分）
• texture_over：覆盖纹理（前景装饰）
• tint_progress：着色

典型用法：游戏血条（半圆形、特殊形状的进度条）。

#4.4 NinePatchRect

用途：九宫格缩放，保证边角不变形。

类比前端：CSS 的 border-image-slice 或 .9.png 图片。

典型用法：对话框背景、面板背景、任何需要圆角/装饰边框的容器。

#4.5 ColorRect

用途：纯色矩形。

核心属性：

• color：颜色

典型用法：半透明遮罩层、分隔线、背景色块。

#五、容器与面板

#5.1 PanelContainer

用途：带背景面板的容器。子节点会显示在一个有边框和背景色的面板上。

典型用法：对话框、设置面板、任何需要视觉边界的区域。

#5.2 TabContainer

用途：标签页切换容器。每个子节点对应一个标签页，点击标签切换显示。

核心属性：

• tab_alignment：标签对齐
• current_tab：当前激活的标签索引
• tab_close_display_policy：关闭按钮显示策略

典型用法：设置页面的多个分类标签、角色属性面板的不同分页。

#5.3 Tree

用途：树形列表，支持展开/折叠。

核心属性：

• allow_reselect：允许重复选中
• allow_rmb_select：允许右键选中
• hide_root：隐藏根节点

典型用法：文件浏览器、技能树、组织架构图。

#5.4 ItemList

用途：列表控件，每项可以有图标和文字。

核心属性：

• max_columns：最大列数
• select_mode：单选/多选
• allow_reorder：允许拖拽排序
• icon_mode：图标显示模式（大图标/小图标）

典型用法：背包物品列表、成就列表、图片选择器。

#六、弹窗与通知

#6.1 Popup / PopupPanel / PopupMenu

用途：弹出层。

节点	用途
Popup	通用弹窗基类
PopupPanel	带面板样式的弹窗
PopupMenu	菜单弹窗（右键菜单、下拉菜单）

信号：

• popup_hide()：弹窗关闭时触发

典型用法：右键上下文菜单、确认删除弹窗、设置子菜单。

#6.2 Window（Godot 4 新增）

用途：独立窗口节点，可以弹出在主窗口之上。

核心属性：

• size：窗口大小
• exclusive：是否独占（弹出时阻断其他交互）
• popup_window：是否作为弹窗使用

类比：类似操作系统层面的弹窗，但在同一个 Godot 窗口内。

#6.3 AcceptDialog / ConfirmationDialog

用途：预制的确认弹窗。

节点	特点
AcceptDialog	只有"确定"按钮
ConfirmationDialog	有"确定"和"取消"按钮

信号：

• confirmed()：点击确定时触发
• canceled()：点击取消时触发

典型用法：删除确认、保存提示、操作成功通知。

#七、滚动与视图

#7.1 ScrollContainer

用途：为子节点提供滚动功能。

核心属性：

• scroll_horizontal / scroll_vertical：当前滚动位置
• scroll_horizontal_enabled / scroll_vertical_enabled：是否允许滚动
• drag_to_scroll：拖拽滚动

类比前端：overflow: auto; 的容器。

典型用法：长列表滚动、聊天记录滚动、地图拖拽浏览。

#7.2 SubViewportContainer

用途：在 UI 中嵌入 3D 渲染区域。

典型用法：3D 角色预览、小地图、嵌入式 3D 场景。

#八、Slider 与进度控制

#8.1 HSlider / VSlider

用途：滑动条。

核心属性：

• value：当前值
• min_value / max_value：范围
• step：步进
• tick_count / ticks_on_borders：刻度显示

类比前端：<input type="range">

典型用法：音量调节、亮度调节、灵敏度设置。

#8.2 Range

用途：滑动条的基类，也可以直接使用。提供 value_changed 信号。

与 Slider 的区别：Range 是抽象基类，Slider 是它的可视化实现。直接用 Range 配合代码可以实现更自定义的进度控制。

#九、特殊控件

#9.1 GraphEdit / GraphNode

用途：节点图编辑器，用于可视化连线编辑。

典型用法：可视化脚本编辑器、技能连线、状态机可视化。

#9.2 CodeEdit

用途：代码编辑器控件，支持语法高亮、代码补全、行号。

核心属性：

• syntax_highlighter：语法高亮器
• gutters_draw_line_numbers：显示行号
• code_completion_enabled：代码补全

典型用法：内置代码编辑器、配置文件编辑器。

#9.3 VideoStreamPlayer

用途：视频播放器。

典型用法：过场动画播放、教程视频嵌入。

#9.4 WebRTC / WebBrowser（插件扩展）

用途：嵌入网页浏览器。需要通过插件实现。

#十、UI 节点关系速查表

复制Control（所有 UI 节点的基类）
├── Container（布局容器）
│   ├── MarginContainer    → 内边距
│   ├── HBoxContainer      → 水平排列
│   ├── VBoxContainer      → 垂直排列
│   ├── GridContainer      → 网格排列
│   ├── FlowContainer      → 流式排列
│   ├── CenterContainer    → 居中
│   ├── SubViewportContainer → 嵌入 3D
│   ├── PanelContainer     → 带背景容器
│   └── TabContainer       → 标签页
├── 基础控件
│   ├── Label              → 文本
│   ├── RichTextLabel      → 富文本
│   ├── TextureRect        → 图片
│   ├── ColorRect          → 纯色块
│   ├── NinePatchRect      → 九宫格
│   ├── ProgressBar        → 进度条
│   ├── TextureProgressBar → 纹理进度条
│   └── VideoStreamPlayer  → 视频
├── 输入控件
│   ├── LineEdit           → 单行输入
│   ├── TextEdit           → 多行输入
│   ├── SpinBox            → 数字输入
│   ├── HSlider / VSlider  → 滑动条
│   └── Range              → 范围控制
├── 按钮家族
│   ├── Button             → 普通按钮
│   ├── CheckBox           → 复选框
│   ├── CheckButton        → 开关
│   ├── LinkButton         → 链接
│   ├── MenuButton         → 菜单按钮
│   ├── OptionButton       → 下拉选择
│   ├── ColorPickerButton  → 颜色选择
│   └── TextureButton      → 图片按钮
├── 列表与树
│   ├── ItemList           → 列表
│   └── Tree               → 树形列表
├── 弹窗
│   ├── Popup              → 通用弹窗
│   ├── PopupPanel         → 面板弹窗
│   ├── PopupMenu          → 菜单弹窗
│   ├── AcceptDialog       → 确认弹窗
│   ├── ConfirmationDialog → 确认/取消弹窗
│   └── Window             → 独立窗口
└── 高级控件
    ├── GraphEdit / GraphNode → 节点图
    ├── CodeEdit             → 代码编辑器
    └── ScrollContainer      → 滚动容器

#十一、Anchor 与 Layout：控制节点在屏幕上的位置

所有 Control 节点都有两个关键属性：

#anchor_left / anchor_top / anchor_right / anchor_bottom

锚点系统，取值 0~1，定义控件相对于父容器的比例位置。例如：

• (0, 0, 1, 1) → 铺满整个父容器
• (0.5, 0.5, 0.5, 0.5) → 固定在正中央（配合 offset 调整大小）

#offset_left / offset_top / offset_right / offset_bottom

在锚点基础上的像素偏移。锚点定大方向，offset 做微调。

类比前端：锚点类似 position: absolute + 百分比定位，offset 类似 margin。

实际应用：

• 血条左上角固定 → anchor (0, 0, 0, 0)
• 小地图右下角 → anchor (1, 1, 1, 1) + 负 offset
• 铺满全屏 → anchor (0, 0, 1, 1) + 全 0 offset

#十二、Theme：统一 UI 风格

Godot 的 Theme 系统让你可以为所有 UI 控件定义统一的视觉样式：

核心属性：

• font：字体
• font_size：字号
• font_color：文字颜色
• bg_color：背景色
• border_width：边框宽度
• border_color：边框颜色
• corner_radius：圆角半径

使用方式：

1. 创建 Theme 资源
2. 在 Theme 编辑器中为每种控件类型设置样式
3. 将 Theme 资源赋给根 Control 节点，所有子节点自动继承

类比前端：类似 CSS 全局样式表 + 继承。定义一次，到处生效。

#十三、实战建议

#怎么选容器？

场景	推荐容器
横排按钮	HBoxContainer
垂直菜单	VBoxContainer
物品格子	GridContainer
可变数量的标签	FlowContainer
居中元素	CenterContainer
需要内边距	MarginContainer

#怎么让 UI 自适应屏幕？

1. 根节点使用全屏锚点 (0, 0, 1, 1)
2. 内部用 Container 子节点自动布局
3. 使用 size_flags_horizontal/vertical 的 EXPAND 控制拉伸比例
4. 避免写死像素值，尽量用锚点和 Container

#性能提示

• UI 节点比 Sprite 节点更重，不要在战斗场景中动态创建大量 UI
• 频繁更新的 UI（如每帧刷新的数字）尽量用 _process 而非信号
• 大量列表项考虑用对象池复用，而不是每次都 instantiate()
• RichTextLabel 比 Label 重，纯文本场景优先用 Label

#总结

Godot 4 的 UI 系统核心就三个概念：

1. Container 决定布局（怎么排列子节点）
2. Control 的锚点决定位置（在屏幕哪里）
3. Theme 决定外观（长什么样）

掌握这三点，你就能搭建出任何复杂的 UI 界面。

记住：先搭 Container 骨架，再填内容，最后调 Theme 美化。这是 Godot UI 开发最顺畅的流程。

参考文档：

• Godot 官方文档 - Control
• Godot 官方文档 - Containers
• Godot 官方文档 - UI 系统教程