godot-ui-containers

决策树：容器类型 → 脚本

需求	优先选择	必须使用的脚本
断点布局 shell / 全屏自适应根容器	Margin + Box 容器	responsive_layout_builder.gd
列数固定、随宽度变化的网格	GridContainer	responsive_grid.gd / responsive_inventory_grid.gd
自动换行的标签块 / 标签	HFlowContainer	responsive_tag_cloud.gd
数千个滚动行	虚拟池（而非原始子节点）	virtual_list.gd
日志 / 聊天自动滚动	ScrollContainer	terminal_autoscroll.gd
UI 中的 3D 角色 / 物品预览	SubViewportContainer	viewport_3d_preview.gd
深层嵌套导致布局卡顿	改用锚点 / 偏移量	performance_anchor_layout.gd
径向 / 轮盘菜单	自定义 Container	custom_radial_container.gd

请勿加载（按场景分类）

场景	加载	请勿加载
库存 / 商店网格	responsive_grid.gd / responsive_inventory_grid.gd	custom_radial_container.gd、viewport_3d_preview.gd
标签云 / 标签块换行	responsive_tag_cloud.gd	网格列脚本、virtual_list.gd
数千条日志 / 聊天记录	virtual_list.gd + terminal_autoscroll.gd	库存 / 径向菜单 / 视口脚本
3D 物品 / 角色预览	viewport_3d_preview.gd	径向菜单 + 库存网格脚本
径向 / 轮盘菜单	custom_radial_container.gd	虚拟列表 + 标签云
深层嵌套 / 布局卡顿	performance_anchor_layout.gd	完整的自适应布局构建器目录

可用脚本

virtual_list.gd

虚拟列表池化——循环使用少量 Control 池 + 占位高度，实现 O(1) 的 ScrollContainer 行处理。

responsive_layout_builder.gd

专家级容器构建器，支持基于断点的自适应布局。

responsive_grid.gd

自动调整的 GridContainer，会根据可用宽度改变列数。

responsive_inventory_grid.gd

专家级动态网格列逻辑，根据可用宽度和物品最小尺寸调整列数。

terminal_autoscroll.gd

安全管理 ScrollContainer。处理添加日志或聊天内容时常见的“一帧延迟”错误。

viewport_3d_preview.gd

高性能 UI 内 3D 预览设置。使用 stretch_shrink 和 transparent_bg 来预览角色。

dynamic_tab_manager.gd

动态生成标签页、自定义标题和关闭标签页逻辑的模式。

responsive_tag_cloud.gd

使用 HFlowContainer 实现列表项自动换行，是标签云和自适应菜单的必备工具。

performance_anchor_layout.gd

优化架构。用轻量级锚点和偏移量逻辑取代深层容器嵌套。

custom_radial_container.gd

专家级自定义容器逻辑，通过 NOTIFICATION_SORT_CHILDREN 实现径向 / 圆形布局。

animated_container_shuffle.gd

交互式 UI 列表的动态同级节点重排和动画逻辑。

aspect_ratio_mini_map.gd

使用 AspectRatioContainer，在窗口流畅调整大小时保持严格的宽高比（例如 1:1、16:9）。

container_size_flags_pro.gd

使用 SIZE_EXPAND_FILL 和 stretch_ratio 实现加权布局的高级尺寸调整逻辑。

永远不要在 UI 容器中做以下操作

• 永远不要忽略 mouse_filter 属性；务必在覆盖层容器上将其设为 PASS 或 IGNORE，以免阻挡对下层按钮的点击。
• 永远不要在 ScrollContainer 中实例化数千个节点；务必使用 虚拟列表池化 — 必须阅读 virtual_list.gd（VScrollBar 钩子 + 单个占位子节点），以实现 O(1) 渲染性能。
• 永远不要手动计算响应式网格的卡片尺寸；务必使用 AspectRatioContainer 锁定比例（例如 2:3），同时让父容器负责缩放。
• 永远不要在 Container 中手动设置子节点的 position 或 size — Container 会在 queue_sort() 期间覆盖子节点变换。请改用 custom_minimum_size 或 size_flags [1]。
• 永远不要忘记设置用于扩展的 size_flags — 默认值为 SIZE_SHRINK_BEGIN。除非设置 SIZE_EXPAND_FILL，否则子节点会保持很小，无法适应响应式容器。
• 永远不要在未设置 columns 的情况下使用 GridContainer — 默认值为 1，会创建简单的垂直列表。若要实现响应式换行，请改用 HFlowContainer [8]。
• 永远不要过度嵌套容器（10 层以上） — 深度嵌套会导致布局重新计算激增。静态留白请使用锚点布局替代中间容器 [16]。
• 永远不要跳过间距覆盖设置 — 默认主题的间距通常太紧。请使用 add_theme_constant_override("separation", value)，留出专业、舒适的空间。
• 永远不要在未设置最小尺寸的情况下使用 ScrollContainer — 否则容器可能会收缩到零，或无限扩展，从而破坏滚动机制。
• 永远不要在添加新子节点的同一帧滚动到该子节点 — 此时布局尚未更新。设置 scroll_vertical 前，必须先执行 await get_tree().process_frame [5]。
• 永远不要通过缩放 SubViewportContainer 来改变其尺寸 — 这会扭曲渲染内容。请调整边距，或改用 stretch 和 stretch_shrink 属性 [2]。
• 永远不要在分层 Viewport 中将 mouse_filter 保持为默认值 — 输入事件可能无法传递到子节点。请使用 MOUSE_FILTER_PASS 或 STOP，确保事件能够向下传递 [6]。
• 永远不要将 GridContainer 用于响应式换行 — 若要根据宽度换行排列项目，请使用 HFlowContainer。GridContainer 会强制使用固定列数 [7]。
• 永远不要在容器内直接为 position 添加动画 — 请对 custom_minimum_size 使用 Tween，在过渡期间平滑地“推开”相邻项 [1]。

---

专家级布局模式

1. 分屏容器（动态）

使用 HSplitContainer 实现本地多人游戏或对比布局的标准模式。

# split_screen.gd
func setup_split(v1: SubViewport, v2: SubViewport):
    var hsplit = HSplitContainer.new()
    var c1 = SubViewportContainer.new()
    c1.stretch = true # Resize viewport to match container
    c1.add_child(v1)
    hsplit.add_child(c1)
    # repeat for c2/v2...

2. 虚拟列表 ScrollContainer（池化）

适用于数千个项目的高性能列表。必须通过 virtual_list.gd（setup_pool + set_data）实现 — 不要将一次性的滚动回收器代码直接粘贴到文档中。

3. 锁定宽高比的卡片

可在任意网格或流式容器中保持比例（例如 2:3）的响应式卡片。

# card_grid.gd
func add_card(texture: Texture2D):
    var arc = AspectRatioContainer.new()
    arc.ratio = 0.66 # 2:3 proportions
    arc.stretch_mode = AspectRatioContainer.STRETCH_FIT
    
    var tr = TextureRect.new()
    tr.texture = texture
    tr.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
    tr.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
    
    arc.add_child(tr)
    grid_container.add_child(arc)

尺寸标志配置指南：必须阅读 container_size_flags_pro.gd — 不要将面向初学者的 SIZE_EXPAND_FILL 教程直接粘贴到文档中。

深入指南（按需查阅）

大模型无知规则：如果通用 Agent 在阅读之前不会了解某项内容，就将其放在这里或 scripts/ 中 — 永远不要删除，只能移动。

主题	参考资料
锚点、标志、间距	container-layout-recipes.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；在路由到相关领域时加载相关技能 — 不要预先加载整个知识网络。

官方文档

• 使用容器 — 关于盒式、网格、流式和分割容器、尺寸标志，以及容器何时会覆盖子项变换的权威指南。
• 尺寸与锚点 — 当你有意跳过深层容器嵌套时，用于实现响应式 Control 布局的锚点预设和偏移。
• Control 节点图库 — Control/Container 类型的可视化目录，帮助 Agent 正确选择 HFlow、Grid 或 Split。
• 自定义 GUI 控件 — 自定义环形布局等所需的 NOTIFICATION_SORT_CHILDREN 和 fit_child_in_rect 模式。
• GUI 导航 — 使用容器构建的菜单中的焦点邻居设置以及键盘/游戏手柄导航。
• 多种分辨率 — 与容器驱动的响应式 UI 交互的拉伸模式和内容缩放。
• Control — 每个布局脚本都会用到的 size_flags_*、custom_minimum_size、mouse_filter 和锚点 API。
• Container — 基础排序生命周期（queue_sort / SORT_CHILDREN），它禁止手动设置子项位置和尺寸。
• ScrollContainer — 滚动条、最小尺寸陷阱，以及日志/聊天 UI 的帧后 scroll_vertical 更新。
• HFlowContainer — 基于宽度换行的标签云和标签列表布局（优先于固定列数的 GridContainer）。
• AspectRatioContainer — 在流式父级尺寸下锁定卡片/小地图的宽高比例。
• SubViewportContainer — 用于 UI 内 3D 预览的 stretch / stretch_shrink，避免缩放失真。

相关技能

前置条件

• godot-project-foundations — 场景树所有权、Control 根节点和项目布局约定；任何响应式菜单在连接容器前都必须遵循这些约定。
• godot-gdscript-mastery — 类型化 Control API、@onready，以及运行时构建网格/标签页时使用的安全子项重建循环。
• godot-signal-architecture — 调整大小、标签页变更和物品栏刷新信号应采用信号向上、调用向下的流转方式，使布局脚本永远不负责管理游戏状态。

补充内容

• godot-ui-theming — 主题常量（separation、边距）和类型变体可设置容器外观样式，无需在布局代码中硬编码颜色。
• godot-ui-rich-text — RichTextLabel 的最小尺寸和 BBCode 内容会影响 ScrollContainer 的高度；布局外壳搭建完成后再配合使用。
• godot-tweening — 为 custom_minimum_size / 重排反馈添加动画，而不是在 Containers 中对 position 使用补间动画。
• godot-input-handling — 为基于 Containers 构建的交互列表/标签页设置焦点、mouse_filter 和动作映射。
• godot-adapt-desktop-to-mobile — 由断点驱动的列数和安全区域边距可与响应式 Grid/HFlow 构建器配合使用。
• godot-inventory-system — 背包网格使用响应式列逻辑；容器负责呈现物品槽，背包负责管理物品数据。
• godot-performance-optimization — 当 ScrollContainer 会生成成千上万个 Controls 时，使用虚拟列表池和浅层锚点布局。

下游 / 使用方

• godot-dialogue-system — 对话选项列表和历史面板采用 Scroll/VBox 布局，可复用自动滚动和间距模式。
• godot-genre-card-game — 手牌弧形布局、拖拽层和牌组 UI 会围绕卡牌 Resources 组合 AspectRatio/HFlow 容器。
• godot-composition-apps — 工具/应用 UI 可在游戏 HUD 之外复用相同的 Container 尺寸标志和拆分模式。

主索引

• godot-master — 当 Agent 从库索引开始时，为 UI Containers 提供路由器和镜像模块入口。