UI 控件节点
最后同步日期：2026-04-15 | Godot 官方原文 — User Interface (UI)
UI 控件节点
UI 控件节点是 Godot 中专门用来做"界面"的节点家族。你可以把它们想象成搭积木——每个 UI 控件就是一块不同形状的积木，拼在一起就能搭出按钮、菜单、血条、设置面板等所有你在游戏或应用里看到的东西。
所有 UI 控件节点都继承自 Control，而 Control 本身又继承自 CanvasItem。这就好比所有"电器"都插在同一个电路上，它们共享一些基本功能（比如能开关、能显示）。
本分类使用说明
每个节点标注了使用频率：★★★ 高频（几乎每个项目都用）、★★ 常用、★ 专项。
各节点页面提供了属性表（5列：属性 | 类型 | 默认值 | 继承自 | 说明）和双语言代码示例。
节点继承关系一览
下面这张图展示了所有 UI 控件节点之间的"家族血缘关系"。箭头从父节点指向子节点，同一个父节点下的兄弟节点功能相近。看懂这张图，你就知道哪些节点是"亲戚"、哪些能力是从"祖先"那里继承来的。
节点总览表
基类与抽象类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| Control | 所有 UI 控件的老祖宗，提供布局基础能力 | ★★★ | 基类 |
| Container | 容器的抽象基类，负责自动排列子控件 | ★★★ | 抽象基类 |
| BaseButton | 所有按钮的抽象基类，提供按钮公共能力 | ★★★ | 抽象基类 |
| Range | 数值范围的抽象基类，提供 min/max/value 框架 | ★★ | 抽象基类 |
按钮类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| Button | 标准按钮，最常见的交互控件 | ★★★ | 查看 |
| TextureButton | 图片按钮，用自定义图片做外观 | ★★ | 查看 |
| LinkButton | 超链接按钮，类似网页超链接 | ★ | 查看 |
| MenuButton | 下拉菜单按钮 | ★ | 查看 |
| OptionButton | 下拉选择按钮 | ★★ | 查看 |
| CheckBox | 复选框，可多选 | ★★ | 查看 |
| CheckButton | 切换开关，滑动开关样式 | ★★ | 查看 |
文字类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| Label | 显示纯文字 | ★★★ | 查看 |
| RichTextLabel | 富文本，支持 BBCode 格式 | ★★ | 查看 |
| LineEdit | 单行输入框 | ★★★ | 查看 |
| TextEdit | 多行文本编辑器 | ★★ | 查看 |
| CodeEdit | 代码编辑器，带行号和语法高亮 | ★ | 查看 |
图片与显示类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| TextureRect | 显示图片 | ★★★ | 查看 |
| NinePatchRect | 九宫格拉伸图片 | ★★ | 查看 |
| ColorRect | 纯色矩形 | ★★ | 查看 |
| Panel | 面板背景 | ★★★ | 查看 |
进度与数值类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| ProgressBar | 进度条 | ★★★ | 查看 |
| TextureProgressBar | 图片进度条 | ★★ | 查看 |
| SpinBox | 数值输入框 | ★★ | 查看 |
| Slider | 滑动条（基类） | ★★ | 查看 |
| HSlider | 水平滑动条 | ★★ | 查看 |
| VSlider | 垂直滑动条 | ★★ | 查看 |
颜色类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| ColorPicker | 颜色选择面板 | ★ | 查看 |
| ColorPickerButton | 颜色选择按钮 | ★ | 查看 |
容器类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| HBoxContainer | 水平排列子控件 | ★★★ | 查看 |
| VBoxContainer | 垂直排列子控件 | ★★★ | 查看 |
| GridContainer | 网格排列子控件 | ★★ | 查看 |
| FlowContainer | 流式排列自动换行（基类） | ★★ | 查看 |
| HFlowContainer | 水平流式排列 | ★★ | 查看 |
| VFlowContainer | 垂直流式排列 | ★★ | 查看 |
| CenterContainer | 居中子控件 | ★★ | 查看 |
| MarginContainer | 给子控件加边距 | ★★ | 查看 |
| ScrollContainer | 可滚动容器 | ★★ | 查看 |
| SplitContainer | 可拖拽分割容器（基类） | ★ | 查看 |
| HSplitContainer | 水平可拖拽分割容器 | ★★ | 查看 |
| VSplitContainer | 垂直可拖拽分割容器 | ★★ | 查看 |
| SubViewportContainer | 嵌入视口容器 | ★ | 查看 |
| AspectRatioContainer | 保持宽高比容器 | ★ | 查看 |
| PanelContainer | 带背景面板的容器 | ★★ | 查看 |
| FoldableContainer | 可折叠容器（Godot 4.4+） | ★★ | 查看 |
列表与选择类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| TabBar | 独立标签栏 | ★★ | 查看 |
| TabContainer | 标签页容器 | ★★ | 查看 |
| Tree | 树形控件 | ★★ | 查看 |
| ItemList | 项目列表控件 | ★★ | 查看 |
对话框与弹出类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| AcceptDialog | 确认对话框 | ★ | 查看 |
| ConfirmationDialog | 确认/取消对话框 | ★ | 查看 |
| PopupMenu | 弹出菜单 | ★ | 查看 |
| FileDialog | 文件选择对话框 | ★★ | 查看 |
滚动条类
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| ScrollBar | 滚动条（基类） | ★ | 查看 |
| HScrollBar | 水平滚动条 | ★ | 查看 |
| VScrollBar | 垂直滚动条 | ★ | 查看 |
其他
| 节点 | 说明 | 频率 | 详细文档 |
|---|---|---|---|
| GraphEdit | 图形编辑器画布 | ★ | 查看 |
| VideoStreamPlayer | 视频播放器 | ★ | 查看 |
按功能速查
| 我想做... | 推荐节点 | 备注 |
|---|---|---|
| 显示文字 | Label | 简单文字 |
| 显示带格式文字 | RichTextLabel | 支持 BBCode |
| 让用户输入一行文字 | LineEdit | 用户名、密码等 |
| 让用户输入多行文字 | TextEdit | 聊天框、备注等 |
| 显示一张图片 | TextureRect | 头像、图标、背景等 |
| 显示可拉伸的背景图 | NinePatchRect | 圆角不变形 |
| 做一个可点击的按钮 | Button | 最常用 |
| 用图片做按钮 | TextureButton | 自定义外观 |
| 做复选框 | CheckBox | 多选场景 |
| 做开关 | CheckButton | 滑动开关样式 |
| 做下拉选择 | OptionButton | 选择难度、角色等 |
| 做下拉菜单 | MenuButton | 文件菜单等 |
| 做超链接按钮 | LinkButton | 打开网页 |
| 显示进度条 | ProgressBar | 血条、加载进度 |
| 用图片做进度条 | TextureProgressBar | 圆形进度等 |
| 让用户拖动调数值 | HSlider / VSlider | 音量、亮度等 |
| 让用户输入精确数值 | SpinBox | 数量、大小等 |
| 水平排列控件 | HBoxContainer | 按钮栏、工具条 |
| 垂直排列控件 | VBoxContainer | 设置面板、列表 |
| 网格排列控件 | GridContainer | 背包、棋盘 |
| 自动换行排列 | HFlowContainer | 标签云、技能列表 |
| 给控件加边距 | MarginContainer | 内边距 |
| 居中一个控件 | CenterContainer | 弹窗内容居中 |
| 做带背景的面板 | PanelContainer | 对话框、信息框 |
| 做可滚动区域 | ScrollContainer | 长列表、长文本 |
| 做标签页切换 | TabContainer | 设置页面 |
| 做可拖动分割面板 | SplitContainer | 编辑器布局 |
| 做背景面板 | Panel | 最简单的背景 |
| 做树形列表 | Tree | 文件浏览器、技能树 |
| 做可选项目列表 | ItemList | 背包列表、歌曲列表 |
| 选颜色 | ColorPicker | 画笔颜色等 |
| 选择文件 | FileDialog | 导入、导出文件 |
| 做节点图编辑器 | GraphEdit | 蓝图编辑器 |
| 播放视频 | VideoStreamPlayer | 过场动画 |
| 做 3D 角色预览 | SubViewportContainer | 角色选择界面 |
节点选择指南
不知道该用哪个 UI 控件？根据你的使用场景，从下面选一个最接近的：
HUD 需要 CanvasLayer
游戏 HUD（血条、分数、小地图等）通常需要放在 CanvasLayer 节点下面，这样 HUD 不会随着 Camera2D 的移动而滚动。设置界面、开始画面则可以直接放在场景根节点下。
CanvasLayer 在工具辅助章节中介绍。
界面需要随窗口缩放吗？
不同场景的 UI 元素，对"窗口大小变化"的响应方式不同：
| 需求 | 做法 | 典型场景 |
|---|---|---|
| 跟着窗口放大缩小 | 套 VBoxContainer / HBoxContainer，锚点设为全屏 | 游戏开始画面、设置面板 |
| 固定在角落 / 边缘 | 直接设锚点（左上、右下等），不套容器 | HUD 血条、小地图、分数 |
| 固定大小居中 | 用 CenterContainer 包裹 | 弹窗内容、对话框 |
| 图片不变形 | 用 AspectRatioContainer | Logo、角色头像 |
| 边距内缩统一 | 用 MarginContainer 包裹 | 所有全屏 UI 的外层 |
快速理解锚点（Anchor）
锚点就是告诉 Godot"这个控件相对于屏幕的哪个位置"。比如血条锚点设在左上角（TopLeft），窗口怎么变它都钉在左上角。设置面板锚点设为全屏（FullRect）+ 容器，窗口放大时面板也跟着撑满。
常见场景搭配
UI 控件节点负责游戏中的所有界面。下面按具体场景逐一展示典型的节点搭配结构。
游戏 HUD
游戏中固定在屏幕上的血条、分数、小地图等。CanvasLayer 做 HUD 层 + ProgressBar 做血条 + Label 做分数。
设置界面
游戏设置面板，需要多种控件组合。TabContainer 做分类 + HSlider 做滑块 + CheckButton 做开关。
游戏开始画面
游戏标题 + 开始按钮的经典布局。CenterContainer 居中 + VBoxContainer 垂直排列。
背包 / 网格列表
用网格排列物品图标的背包系统。ScrollContainer 做滚动 + GridContainer 做网格 + TextureRect 做物品图标。