跳转至

Godot UI — 快速参考

最后验证:2026-02-12 | 引擎:Godot 4.6

自 ~4.3 以来的变更(LLM 截止)

4.6 变更

  • 双焦点系统:鼠标/触摸焦点现在与键盘/游戏手柄焦点分离
  • 视觉反馈因输入方式而异
  • 自定义焦点实现可能需要更新
  • TabContainer:标签页属性现在可直接在 Inspector 中编辑
  • TileMapLayer 场景瓦片旋转:场景瓦片现在可以像图集瓦片一样旋转

4.5 变更

  • FoldableContainer:新增手风琴式 UI 节点,用于可折叠区域
  • 递归 Control 行为:通过单个属性禁用整个节点层级的鼠标/焦点
  • 屏幕阅读器支持:Control 节点可与 AccessKit 配合使用
  • 实时翻译预览:可在编辑器中测试不同区域设置
  • RichTextLabel.push_meta:新增可选 tooltip 参数(自 4.4 起)

4.4 变更

  • GraphEdit.connect_node:新增可选 keep_alive 参数

当前 API 模式

主题与样式(4.6)

# Editor uses new "Modern" theme by default
# For game UI, use custom themes as before:
var theme := Theme.new()
theme.set_color(&"font_color", &"Label", Color.WHITE)
theme.set_font_size(&"font_size", &"Label", 24)

焦点管理(4.6 — 已变更)

# Keyboard/gamepad focus (grab_focus still works)
func _ready() -> void:
    %StartButton.grab_focus()

# IMPORTANT: In 4.6, mouse hover is separate from keyboard focus
# Both can be active simultaneously on different controls
# Test your UI with BOTH mouse and keyboard/gamepad

# Focus neighbors (unchanged)
%Button1.focus_neighbor_bottom = %Button2.get_path()
%Button1.focus_neighbor_right = %Button3.get_path()

FoldableContainer(4.5 — 新增)

# Accordion-style collapsible container
# Add as parent of content you want to make collapsible
# Children show/hide when header is clicked
# Configure via editor properties or code

递归禁用(4.5 — 新增)

# Disable all mouse/focus interactions for a hierarchy
# Useful for disabling entire menu sections
%SettingsPanel.mouse_filter = Control.MOUSE_FILTER_IGNORE
# In 4.5+, this can propagate recursively to children

本地化就绪 UI(最佳实践)

# Use tr() for all visible strings
label.text = tr("MENU_START_GAME")

# Use auto-wrap for labels (text length varies by language)
label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART

# Test with live translation preview in editor (4.5+)

常见错误

  • 假设 grab_focus() 会影响鼠标焦点(4.6 中仅键盘/游戏手柄可用)
  • 升级到 4.6 后未同时使用鼠标和游戏手柄测试 UI
  • 硬编码字符串而不使用 tr() 进行本地化
  • 未使用 FoldableContainer 实现可折叠 UI(4.5 新增,比自定义方案更简洁)

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/Claude-Code-Game-Studios