godot-ui

Godot UI

根据布局规则、可复用的视觉资源和明确的交互状态来构建界面。不要用一堆坐标来实现响应式布局，也不要让指针输入成为唯一可用的操作方式。

编辑前检查

在更改场景、脚本、主题或项目设置之前，先完成以下检查。

1. 找到 project.godot 并确认项目根目录。读取 config/features、显示基准尺寸、拉伸模式和宽高比、GUI 主题设置、本地化设置以及 Input Map 操作。
2. 如果有项目指定的 Godot 可执行文件，使用它运行 --version。使用该确切 Godot 4.x 版本对应的 API 和 Inspector 属性名称。
3. 检查有代表性的 UI 场景和脚本。记录根节点类型、CanvasLayer 用法、锚点和容器模式、尺寸标志、唯一节点名称、信号连接方式、GDScript 类型约定、场景构成和命名方式。
4. 检查现有的 .tres 主题、字体、字体回退、图标、本地化文件、UI 缩放设置，以及所有已定义的交互状态。
5. 在预期设计尺寸、支持的最小尺寸、最大实用尺寸和非常规宽高比下运行当前 UI。如果存在翻译，至少测试一种较长的语言。
6. 不使用鼠标进行导航。记录初始焦点、Tab 顺序、方向导航邻接项、确认／取消行为、焦点可见性，以及任何会困住焦点或导致焦点丢失的控件。

未经确认项目范围内的拉伸、主题或输入设置对所有现有界面的影响，不要为了修复单个场景而覆盖这些设置。

核心布局规则

• 使用跟随视口或 UI 区域的 Control 根节点。
• 使用锚点相对于父节点放置主要区域。
• 使用容器在这些区域内排列动态子项。
• 让 Container 控制其直接子项的位置和尺寸。使用尺寸标志、拉伸比例、最小尺寸、主题间距和包装控件，而不要用偏移量与其对抗。
• 使用 MarginContainer 设置内边距，使用 PanelContainer 创建经过样式化的内容表面，使用盒式容器排列行和列，使用 GridContainer 指定已知的列数。
• 当有效内容可能超出可用空间时，使用 ScrollContainer。不要把文本和控件缩小到勉强塞进空间。
• 仅在触控目标、易读控件、艺术边界或布局约束确有需要时，才保留固定偏移和最小尺寸。
• 如果屏幕空间中的游戏 UI 必须独立于世界摄像机，则将其置于 CanvasLayer 下。

工作流

1. 定义支持的窗口尺寸、宽高比、UI 缩放范围、输入设备、本地化语言和无障碍选项。
2. 在选择节点类型之前，先勾勒语义区域和阅读顺序。
3. 使用占位内容，通过锚点和容器搭建结构树。先确保布局能随尺寸变化正常工作，再进行样式设计。
4. 添加标签、字段、按钮、列表、图像和动态内容。使用有意义的名称，并为重复组件创建可复用子场景。
5. 在最合适的最高层根节点上应用共享的 Theme。使用类型变体定义主要、危险、紧凑或标题等角色；仅在确有例外时使用节点级覆盖。
6. 连接 pressed、value_changed、item_selected 和 text_submitted 等语义信号。只有标准控件无法表达自定义交互时，才使用 _gui_input。
7. 为每个屏幕和模态界面定义焦点进入方式、顺序、方向移动、激活方式、取消行为和焦点恢复。
8. 添加无障碍支持：持久标签、可见焦点、足够的对比度、非颜色提示、可缩放文本、减少动态效果、适用时可重新映射的控件，以及清晰易读的状态／错误反馈。
9. 同时验证布局、主题状态、输入路径、本地化和运行时更新。

类型化响应式示例

此示例会根据实际可用宽度，将表单网格从两列改为一列，而不是猜测设备类型。

extends Control

@export_range(320.0, 1600.0, 8.0) var compact_width: float = 720.0
@onready var settings_grid: GridContainer = %SettingsGrid

func _ready() -> void:
    resized.connect(_refresh_layout)
    _refresh_layout()

func _refresh_layout() -> void:
    settings_grid.columns = 1 if size.x < compact_width else 2

优先采用能通过容器自然重排的布局。只有当信息结构确实会在受限宽度下发生变化时，才添加断点脚本。

输入与焦点约定

• 只将焦点赋予可交互控件。确认自定义控件使用了合适的 focus_mode。
• 屏幕变为可见后再设置初始焦点。关闭对话框或子屏幕后，将焦点还给打开它的控件。
• 除非项目有意重新映射，否则保留内置 ui_* 动作语义。将游戏操作与 UI 导航分开。
• 确保键盘和控制器用户都能访问每个操作，并能离开每个复合控件。
• 让焦点指示器在视觉上明显区别于悬停和按下状态。
• 尽可能让标准控件处理文本编辑、选择、剪贴板、IME 和辅助语义。
• 使用合适的 mouse_filter 标记装饰性叠加层，避免其阻挡下方控件。
• 在所属屏幕或导航层处理取消/返回操作，而不是在每个子项中分别处理。

验证

• 使用匹配的编辑器导入并解析项目。若支持，请运行 <godot> --headless --path <project> --editor --quit 并检查所有输出。
• 在支持范围内连续调整窗口大小。测试适用于项目的横向、纵向、超宽、窄屏和高 DPI 场景。
• 检查裁切、重叠、尺寸为零的控件、不需要的滚动条、过多空白、纹理变形，以及内容超出面板的情况。
• 将标签替换为长文本、多行文本、空文本、大数字、支持时的从右至左文本，以及运行时生成的内容。
• 增大 UI 或内容缩放比例，确认布局会重新排布而不是被裁切。
• 测试每种适用的控件状态：正常、悬停、按下、聚焦、禁用、已选中、无效、加载中和空状态。
• 从新打开的屏幕开始，仅使用 Tab 和 Shift+Tab、仅使用方向操作、仅使用确认/取消操作，以及使用受支持的控制器进行导航。
• 在控件重叠或位于游戏场景上方时，测试鼠标、触摸和键盘事件的传播。
• 验证焦点会进入模态界面、在需要时保持在其中、返回打开它的控件，并在场景切换后仍然可见。
• 根据具体引擎/平台支持情况，检查对比度、焦点提示、非颜色状态指示、减少动态效果行为、文本替代内容和错误播报。
• 运行集成场景，而不只是孤立组件；并报告任何未经测试的设备、区域设置或辅助技术行为。

常见陷阱

• 在容器的直接子项上设置偏移，然后疑惑容器为何重置了这些偏移。
• 在列表或表单的每个项上都使用锚点，而不是让容器管理动态内容。
• 使用 scale 让 Control 适应布局，这可能导致视觉模糊，并使输入几何与布局意图脱节。
• 将分辨率、标签长度、字体度量或输入设备硬编码为单一值。
• 应用数十个主题覆盖项，掩盖实际设计系统。
• 遗漏 focus 样式，或让焦点在视觉上与悬停状态完全相同。
• 在隐藏屏幕变为可见之前抢占焦点，或者完全不设置初始焦点。
• 在 _input 中处理标准按钮激活，导致重复激活或绕过 GUI 事件路由。
• 让带有 MOUSE_FILTER_STOP 的装饰性 Control 阻挡其下方的按钮。
• 每次按键都重写 LineEdit.text，却不保留光标、选择、粘贴和 IME 行为。
• 只用工具提示或颜色来解释控件或错误。
• 假设所有 Godot 4.x 版本都提供相同的原生辅助功能 API。检查具体版本，并验证每个目标平台。

参考资料

• 响应式布局
• 主题和视觉状态
• 输入、焦点和无障碍功能