Back to Details

godot-ui-containers

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UI Containers

UI 容器

Container auto-layout, size flags, anchors, and split ratios define responsive UI systems.
容器自动布局、size flags、锚点和分割比例共同构成了响应式UI系统。

Available Scripts

可用脚本

responsive_layout_builder.gd

responsive_layout_builder.gd

Expert container builder with breakpoint-based responsive layouts.
基于断点的响应式布局专家容器构建工具。

responsive_grid.gd

responsive_grid.gd

Auto-adjusting GridContainer that changes column count based on available width. Essential for responsive inventory screens and resizing windows.
可根据可用宽度自动调整列数的GridContainer。是构建响应式物品栏界面和窗口大小调整功能的必备工具。

NEVER Do in UI Containers

UI容器使用禁忌

  • NEVER set child position/size manually in Container — 
    child.position = Vector2(10, 10)
    inside HBoxContainer? Container overrides it on layout. Use 
    custom_minimum_size
    OR margins instead.
  • NEVER forget size_flags for expansion — Child in VBoxContainer doesn't expand? Default is SHRINK. Set 
    size_flags_vertical = SIZE_EXPAND_FILL
    for fill behavior.
  • NEVER use GridContainer without columns — 
    GridContainer
    with default 
    columns = 1
    ? Vertical list, wrong layout. ALWAYS set 
    columns
    property to grid width.
  • NEVER nest too many containers — 10 levels of HBox in VBox in HBox? Re-layout overhead + hard to debug. Flatten OR use Control with custom layout.
  • NEVER skip separation override — Default 4px separation? Cramped UI. Override with 
    add_theme_constant_override("separation", value)
    for breathing room.
  • NEVER use ScrollContainer without minimum size — ScrollContainer with no 
    custom_minimum_size
    ? Expands infinitely, no scrolling. Set minimum OR use anchors.
gdscript
undefined
  • 切勿在Container中手动设置子节点的位置/尺寸——在HBoxContainer中设置
    child.position = Vector2(10, 10)
    ？容器会在布局时覆盖该设置。请改用
    custom_minimum_size
    或边距。
  • 切勿忘记设置用于扩展的size_flags——VBoxContainer中的子节点无法扩展？默认值为SHRINK。设置
    size_flags_vertical = SIZE_EXPAND_FILL
    可实现填充效果。
  • 切勿在未设置列数的情况下使用GridContainer——默认
    columns = 1
    的
    GridContainer
    会变成垂直列表，这是错误的布局方式。务必将
    columns
    属性设置为网格宽度。
  • 切勿过度嵌套容器——10层HBox套VBox套HBox的嵌套结构？会导致重布局开销增大且难以调试。请简化嵌套结构，或使用自定义布局的Control节点。
  • 切勿忽略间距覆盖——默认4px的间距会让UI显得拥挤。使用
    add_theme_constant_override("separation", value)
    来调整间距，为UI留出呼吸空间。
  • 切勿在未设置最小尺寸的情况下使用ScrollContainer——未设置
    custom_minimum_size
    的ScrollContainer会无限扩展，无法实现滚动。请设置最小尺寸或使用锚点。
gdscript
undefined

VBoxContainer example

VBoxContainer示例

Automatically stacks children vertically

自动垂直堆叠子节点

Children:

子节点：

Button ("Play")

按钮（"开始游戏"）

Button ("Settings")

按钮（"设置"）

Button ("Quit")

按钮（"退出"）

Set separation between items

设置项目之间的间距

$VBoxContainer.add_theme_constant_override("separation", 10)
undefined
$VBoxContainer.add_theme_constant_override("separation", 10)
undefined

Responsive Layout

响应式布局

gdscript
undefined
gdscript
undefined

Use anchors and size flags

使用锚点和size flags

func _ready() -> void: # Expand to fill parent $MarginContainer.set_anchors_preset(Control.PRESET_FULL_RECT)
# Add margins
$MarginContainer.add_theme_constant_override("margin_left", 20)
$MarginContainer.add_theme_constant_override("margin_right", 20)
undefined
func _ready() -> void: # 扩展以填充父容器 $MarginContainer.set_anchors_preset(Control.PRESET_FULL_RECT)
# 添加边距
$MarginContainer.add_theme_constant_override("margin_left", 20)
$MarginContainer.add_theme_constant_override("margin_right", 20)
undefined

SizeFlags

SizeFlags

gdscript
undefined
gdscript
undefined

Control how children expand in containers

控制子节点在容器中的扩展方式

button.size_flags_horizontal = Control.SIZE_EXPAND_FILL button.size_flags_vertical = Control.SIZE_SHRINK_CENTER
undefined
button.size_flags_horizontal = Control.SIZE_EXPAND_FILL button.size_flags_vertical = Control.SIZE_SHRINK_CENTER
undefined

Reference

参考资料

Related

相关内容

  • Master Skill: godot-master
  • 核心技能：godot-master