Godot UI

Control 界面：场景里用 Container 和 anchors 搭，项目级 Theme 统一外观，用内置的 ProgressBar、RichTextLabel、翻译系统和焦点导航。

范围

先查内置

做法

布局

HUD 与菜单在场景里搭：根 Control 用 Full Rect preset，其下嵌套 Container。

[node name="Hud" type="Control"]
layout_mode = 3
anchors_preset = 15
anchor_right = 1.0
anchor_bottom = 1.0
mouse_filter = 2

[node name="Margin" type="MarginContainer" parent="."]
layout_mode = 1
anchors_preset = 15
anchor_right = 1.0
anchor_bottom = 1.0
theme_type_variation = &"HudMargin"

[node name="Row" type="HBoxContainer" parent="Margin"]
layout_mode = 2

[node name="HealthBar" type="ProgressBar" parent="Margin/Row"]
custom_minimum_size = Vector2(240, 24)
layout_mode = 2
show_percentage = false

• 有 Camera2D 时 HUD 放 CanvasLayer 下，否则随相机移动
• CanvasLayer.layer 默认 1，大的在上
• 根 Control 设 mouse_filter = 2 即 IGNORE，否则吃掉所有点击
• Container 决定子节点位置，子节点只表达尺寸需求

浮动控件，如跟随角色的血条、弹出提示，才用代码摆，仍用 preset：

extends Control

func _ready() -> void:
	set_anchors_and_offsets_preset(Control.PRESET_CENTER_BOTTOM, Control.PRESET_MODE_MINSIZE, 32)

• set_anchors_preset 只改锚点，不改偏移
• 一般用 set_anchors_and_offsets_preset
• PRESET_FULL_RECT 铺满，PRESET_TOP_WIDE 贴顶拉宽

容器限制

Container 在子节点变化和 queue_sort() 时重排，子节点的 position size 动画会被覆盖。

• 动画改动 scale modulate rotation，或外包一层普通 Control
• 按中心缩放、Label 换行、滚动区宽度见 references/layout.md

Theme

外观放一个 Theme 资源，项目设置里挂成全局默认：

[gui]

theme/custom="res://ui/theme/main.tres"
theme/custom_font="res://ui/fonts/main.ttf"

• 对应 gui/theme/custom 与 gui/theme/custom_font
• 任何 Control 不设 theme 也继承它，代码建的 UI 同样继承
• 局部换主题：给 Control 设 theme，Control 与 Window 后代继承
• 遇到其他类型的节点，继承断开
• 颜色字号间距在 Theme 编辑器里改，脚本只读：get_theme_color(&"font_color", &"Label")
• 同类控件多种样式用 theme type variation，单个 Label 用 label_settings
• StyleBox 种类、变体、LabelSettings 见 references/theme.md

单个节点的一次性差异才用 override，如血条填充色随阵营变：

extends ProgressBar

func set_team_color(color: Color) -> void:
	var fill := get_theme_stylebox(&"fill").duplicate() as StyleBoxFlat
	fill.bg_color = color
	add_theme_stylebox_override(&"fill", fill)

• duplicate() 必须有，否则改到 Theme 里共享的 StyleBox

血条

ProgressBar 做纯色条，TextureProgressBar 做贴图条或环形条。样式在 Theme 里改 fill 与 background。

缓动与受伤残影：

extends Control

@onready var _front: ProgressBar = %Front
@onready var _chip: ProgressBar = %Chip

var _tween: Tween

func set_health(value: float) -> void:
	_front.value = value
	if _tween:
		_tween.kill()
	_tween = create_tween()
	_tween.tween_interval(0.4)
	_tween.tween_property(_chip, "value", value, 0.3).set_trans(Tween.TRANS_CUBIC).set_ease(Tween.EASE_OUT)

• 前景条与残影条同位置叠放，残影条在下，填充用浅色
• 前景条 background 设 StyleBoxEmpty，否则盖住残影条

RichTextLabel

• 带自定义效果的 RichTextLabel 每帧处理，不用时隐藏
• 标签清单与效果示例见 references/richtext.md

多分辨率

• 4.7 起新建项目默认 canvas_items 加 expand
• 除 keep 外，HUD 靠 anchors 和 Container 贴边
• 各取值、整数缩放、界面缩放、安全区见 references/layout.md

本地化

玩家可见文本一律进翻译表，含按钮文字、提示、地点名。

• 复数形式不止两种，不写 if count == 1
• tr_n 前两个参数写带 %d 的英文原文，它是键也是回退文本
• CSV 复数要 ?plural 列 4.6+，4.5 及以前用 PO
• tr() 的结果切换语言后不自动更新，在 NOTIFICATION_TRANSLATION_CHANGED 里重设：

extends Label

var _count: int = 0

func _notification(what: int) -> void:
	if what == NOTIFICATION_TRANSLATION_CHANGED:
		text = tr_n("%d item", "%d items", _count) % _count

• 导入、注册、伪本地化、字体回退见 references/localization.md

焦点导航

• 场景启动后须有控件拿焦点，否则方向键和手柄无反应
• 写法：$StartButton.grab_focus.call_deferred()
• 控件隐藏会丢焦点，面板重新显示要再抓
• focus_mode、邻居、弹窗还焦点、无障碍名称见 references/focus-navigation.md

按键提示

• 提示文本从 InputMap.action_get_events 取，改键后自动跟随
• 绑定 physical_keycode 时用 as_text_physical_keycode()
• 手柄按 InputEventJoypadButton.button_index 映射到自己的图标
• 完整写法与键帽字母见 references/focus-navigation.md

输入顺序

_input、_gui_input、_shortcut_input、_unhandled_key_input、_unhandled_input，依次传递。

• 不手写鼠标是否在 UI 上的判断

mouse_filter

• 滚轮例外：mouse_force_pass_scroll_events 默认 true，STOP 也放行
• HUD 根节点、装饰 ColorRect TextureRect Panel、按钮上的图标设 IGNORE
• 子树关鼠标：mouse_behavior_recursive = Control.MOUSE_BEHAVIOR_DISABLED 4.5+

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法
• references/localization.md：CSV 与 PO 导入、注册翻译、复数与上下文、TranslationServer、伪本地化、字体回退
• references/theme.md：StyleBox 种类与代码构造、theme type variation、LabelSettings
• references/layout.md：容器排版限制、stretch 各取值、整数缩放、界面缩放、安全区
• references/focus-navigation.md：手柄焦点导航、focus_mode、按键提示与键帽字母、设备切换、无障碍
• references/richtext.md：BBCode 标签速查、自定义 RichTextEffect、打字机
• references/settings-menu.md：设置即时生效、离开即保存与按应用保存、未保存状态显示、窗口模式与尺寸的确认倒计时和还原、全屏与窗口尺寸陷阱、启动参数恢复入口、失焦暂停
• https://docs.godotengine.org/en/stable/tutorials/ui/index.html
• https://docs.godotengine.org/en/stable/tutorials/i18n/index.html
• https://docs.godotengine.org/en/stable/tutorials/ui/gui_navigation.html