responsive-ui

Godot 4.3+ 中的自适应 UI

所有示例均以 Godot 4.3+ 为目标，不使用已弃用的 API。先展示 GDScript，再展示 C#。

相关技能： godot-ui 用于 Control 节点布局和主题，export-pipeline 用于平台专属导出设置，godot-project-setup 用于初始项目分辨率设置，input-handling 用于触控与桌面输入适配，localization 用于按区域设置调整布局，mobile-development 用于安全区域和刘海屏处理。

---

1. 分辨率项目设置

在 Project > Project Settings > Display > Window 中配置基础分辨率和拉伸行为。

project.godot 的 [display] 部分中的关键设置及其键：

设置	project.godot 键	推荐值
视口宽度	window/size/viewport_width	1920（或你的基础设计宽度）
视口高度	window/size/viewport_height	1080（或你的基础设计高度）
拉伸模式	window/stretch/mode	canvas_items（适用于大多数游戏）
拉伸纵横比	window/stretch/aspect	expand（填满屏幕）或 keep（添加黑边）
缩放因子	window/stretch/scale	1
缩放模式	window/stretch/scale_mode	fractional；像素艺术使用 integer

Godot 4.7+： 在 Godot 4.7 中新建的项目已默认将 display/window/stretch/mode 设为 canvas_items，并将 display/window/stretch/aspect 设为 expand（之前为 disabled / keep）——上述推荐值现在就是开箱即用的默认值。旧版本创建的项目不受影响（属性默认值仍为 disabled），因此升级时请明确设置这两项。请参阅 4.7 迁移指南。

引擎会在启动时读取这些设置一次；之后使用 ProjectSettings.set_setting() 修改它们不会生效。运行时请改为设置对应的 Window 属性：

GDScript：

# Read current viewport size
var viewport_size: Vector2 = get_viewport().get_visible_rect().size

# Change stretch mode at runtime (takes effect immediately)
get_window().content_scale_mode = Window.CONTENT_SCALE_MODE_CANVAS_ITEMS

C#：

// Read current viewport size
Vector2 viewportSize = GetViewport().GetVisibleRect().Size;

// Change stretch mode at runtime (takes effect immediately)
GetWindow().ContentScaleMode = Window.ContentScaleModeEnum.CanvasItems;

---

2. 拉伸模式比较

模式	project.godot 值	渲染方式	最适合
canvas_items	"canvas_items"	按窗口分辨率渲染；2D 节点和 UI 从设计分辨率缩放，因此文字保持清晰	大多数 2D 游戏和 UI 占比较高的游戏
viewport	"viewport"	整个视口按设计分辨率渲染后再拉伸；不会进行亚像素混合	需要像素级精确输出的像素艺术游戏
disabled	"disabled"	不自动缩放；视口大小与窗口一致，因此更大的窗口会以相同像素尺寸显示更多内容（锚点和容器仍会进行布局）	复杂的自定义缩放、使用 Control HUD 的 3D 游戏

如何选择：

• canvas_items — 默认推荐。可在任意分辨率下平滑缩放。使用 Control 节点和锚点构建的 UI 会自然适应。与 content_scale_factor 配合时，文字和图标在高 DPI 下仍保持清晰。
• viewport — 将渲染锁定为设计分辨率。搭配整数缩放和最近邻过滤，可呈现经典的像素级精确效果。除非你有意想要粗大的像素，否则避免用于高 DPI 显示屏。
• disabled — 需要完全手动控制时使用，例如 3D 游戏中的 UI 必须适应安全区域或特殊纵横比，且不希望 Godot 对其缩放。

---

3. 宽高比处理

通过 Project > Project Settings > Display > Window > Stretch > Aspect 或 window/stretch/aspect 键设置。

模式	视觉效果	适用场景
keep	添加上下黑边（信箱式）或左右黑边（柱状式）——精确保留设计区域	布局固定且不得裁切的游戏（例如基于分数的街机游戏、益智游戏）
expand	完全填满屏幕；在更宽或更高的显示屏上，可见游戏区域会扩大	动作游戏、平台游戏——可见游戏区域更大是优势，而非问题
keep_width	宽度固定；在更高的屏幕上扩展高度（移动设备竖屏）	对水平对齐要求严格的竖屏移动游戏
keep_height	高度固定；在更宽的屏幕上扩展宽度（横屏）	对垂直对齐要求严格的横屏游戏（例如横向卷轴游戏的 HUD）

对于面向桌面和移动设备的游戏，expand 搭配自适应 UI 是最灵活的选择。将 HUD 元素锚定到屏幕边缘，使其随扩展后的可见区域移动。

---

4. 像素艺术设置

若要制作清晰的像素艺术游戏：设置 Project Settings → Display → Window → Stretch → Mode = viewport，将基础分辨率设为原生像素尺寸（例如 320×180），并设置 Window Width/Height Override（例如 1280×720），以便测试时使用更大的窗口。使用整数缩放（Stretch → Scale Mode = integer）以避免像素不均匀。

完整的项目设置、整数缩放脚本和最近邻滤镜覆盖设置，请参阅 references/pixel-art-setup.md。

---

5. DPI 缩放

对于 Retina／高 DPI 显示屏：设置 content_scale_factor，按比例缩放整个 UI。运行时调用 DisplayServer.screen_get_dpi()，根据设备自适应缩放。

有关 content_scale_factor 设置方法和 DPI 查询模式，请参阅 references/dpi-scaling.md。

---

6. 移动设备注意事项

移动设备有四项特定注意事项：触摸输入（点击、滑动、多点触控）、安全区域内边距（避开刘海／灵动岛）、方向锁定（固定为竖屏／横屏）、虚拟键盘（处理键盘的显示／隐藏，避免遮挡 UI）。

有关每项注意事项的完整 GDScript，以及 iOS／Android 的细节，请参阅 references/mobile.md。

---

7. 自适应布局

锚点预设和 Container 节点可以处理大部分工作。使用 size_flags_horizontal/vertical（FILL、EXPAND、SHRINK_CENTER、SHRINK_END）控制子项如何占用容器空间。通过 get_viewport().size_changed 检测运行时分辨率变化。

有关锚点与容器策略、分辨率变化检测以及完整的 size_flags 参考，请参阅 references/adaptive-layouts.md。

---

8. 测试多种分辨率

编辑器预览尺寸

在编辑器视口中，使用 Editor > Editor Settings > Run > Window Placement，以指定尺寸启动游戏；也可以使用 2D 编辑器工具栏中的视口尺寸选择器。

在 Project > Project Settings > Display > Window > Size > Window Width/Height Override 下设置测试窗口尺寸——游戏窗口会以该尺寸打开，而基础视口尺寸保持不变。

--resolution 命令行标志

从命令行启动，并指定覆盖分辨率：

# Windows
godot.exe --path "C:/projects/mygame" --resolution 1280x720

# Linux / macOS
godot --path /projects/mygame --resolution 1280x720

# Run an exported binary at a specific size
./mygame.x86_64 --resolution 375x812

常见测试分辨率

分辨率	宽高比	常见用途
1920×1080	16:9	标准 1080p 桌面／电视
2560×1440	16:9	1440p 高 DPI 桌面
1280×720	16:9	低端桌面／最低目标分辨率
640×360	16:9	像素艺术基础分辨率（320×180 的 2 倍）
2732×2048	4:3	iPad Pro — 测试非 16:9 宽高比
390×844	~19.5:9	iPhone 14 竖屏
844×390	~19.5:9	iPhone 14 横屏
1080×2400	20:9	Android 高屏竖屏
360×800	~20:9	Android 低端竖屏

策略： 始终在基础设计分辨率、一种宽于 16:9 的分辨率（例如 21:9 超宽屏）以及一种更高的分辨率（例如手机竖屏）下进行测试。这三种情况能捕获大多数布局问题。

---

9. 检查清单

• 基础视口大小（viewport_width / viewport_height）与编辑器中的设计画布相匹配
• 有意选择拉伸模式：大多数游戏使用 canvas_items，像素艺术使用 viewport
• 选择宽高比模式：除非固定布局内容需要 keep，否则使用 expand
• 像素艺术游戏使用 viewport 拉伸 + Nearest 纹理过滤器 + integer 拉伸缩放模式
• 所有 HUD Control 节点都使用锚点锚定到最近的边缘，而非固定的 position 值
• 为按钮和交互元素设置 custom_minimum_size，避免尺寸小于触控目标大小（建议移动端最小为 44×44 px）
• 对应填满空间的元素，将 size_flags_horizontal / size_flags_vertical 设为 SIZE_EXPAND_FILL
• 在布局需要响应窗口大小变化的位置，连接 get_viewport().size_changed 信号
• 从 DisplayServer.get_display_safe_area() 读取安全区域内边距，并应用到根 MarginContainer
• 启动时根据 DisplayServer.screen_get_dpi() 设置 content_scale_factor，以适配高 DPI / Retina 显示屏
• 使用 InputEventScreenTouch / InputEventScreenDrag 处理触控输入，不要只使用鼠标事件
• 将屏幕方向锁定为正确模式（SCREEN_LANDSCAPE / SCREEN_PORTRAIT），或在需要旋转时设为 SCREEN_SENSOR
• 显示虚拟键盘后查询其高度，并在移动端据此将 UI 内容向上移
• 至少在以下分辨率下进行测试：设计分辨率、一种超宽屏分辨率（21:9）以及一种手机竖屏分辨率
• 在 CI 或试玩脚本中使用 --resolution 标志，自动执行多分辨率冒烟测试