最后同步日期：2026-04-15 | Godot 官方原文 — AspectRatioContainer

AspectRatioContainer

节点继承关系

继承链：Node → CanvasItem → Control → Container → AspectRatioContainer

Container

类型	名称	说明
信号	sort_children	子节点排列发生变化
方法	FitChildInRect()	调整子节点到指定矩形内

Control

类型	名称	说明
属性	Size	控件尺寸
属性	Position	控件位置
属性	AnchorsPreset	锚点预设
属性	GrowDirection	超出容器时的扩展方向
属性	MouseFilter	鼠标事件过滤（停止 / 通过 / 忽略）
属性	FocusMode	焦点模式（无 / 单击 / 全部）
信号	gui_input	接收到 GUI 输入事件
信号	mouse_entered	鼠标进入控件区域
信号	mouse_exited	鼠标离开控件区域
信号	focus_entered	获得焦点
信号	focus_exited	失去焦点
信号	resized	尺寸变化
方法	GrabFocus()	获取焦点
方法	ReleaseFocus()	释放焦点
方法	SetAnchorsPreset()	设置锚点预设
方法	GetMinimumSize()	获取最小尺寸

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

AspectRatioContainer 是一个"保持子节点宽高比不变"的容器。不管窗口怎么拉伸、容器大小怎么变，里面的内容始终保持原来的比例——不会变胖也不会变瘦。打个比方：就像你用手机看视频时，不管横屏还是竖屏，视频画面始终不会变形，要么上下留黑边，要么左右留黑边。

使用频率：★★ 偶尔使用（视频播放区域等需要固定比例的场景）

节点用途

• 保持子节点的固定宽高比
• 视频播放区域
• 图片展示区

使用场景

• 游戏中的视频播放区域
• 图片展示区（防止变形）
• 预览窗口

常用节点搭配

• 里面通常放 TextureRect 或 VideoStreamPlayer

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
ratio	float	1.0	—	目标宽高比（宽 / 高）
stretch_mode	枚举	Fit	—	拉伸模式：Fit（等比缩小适配）、Cover（等比放大覆盖）、Width（以宽度为准）、Height（以高度为准）
alignment_horizontal	枚举	Center	—	水平对齐方式
alignment_vertical	枚举	Center	—	垂直对齐方式

信号

信号	触发时机	参数
（AspectRatioContainer 没有特有信号）	—	—

常用方法

继承自 Container 的所有方法。

代码示例

C

using Godot;

// 一个始终保持 16:9 宽高比的视频播放区域
public partial class VideoArea : AspectRatioContainer
{
    public override void _Ready()
    {
        Ratio = 16f / 9f;  // 宽高比 16:9
        StretchMode = AspectRatioContainer.StretchModeEnum.Fit;  // 等比适配
        AlignmentHorizontal = AspectRatioContainer.AlignmentMode.Center;
        AlignmentVertical = AspectRatioContainer.AlignmentMode.Center;

        Size = new Vector2(640, 480);  // 容器可以任意大小，内容始终保持比例

        // 里面放一张图片作为示例（实际可能是 VideoStreamPlayer）
        var image = new TextureRect();
        image.Texture = GD.Load<Texture2D>("res://icon.svg");
        image.StretchMode = TextureRect.StretchModeEnum.KeepAspectCentered;
        image.ExpandMode = TextureRect.ExpandModeEnum.IgnoreSize;
        AddChild(image);
    }
}

GDScript

# 一个始终保持 16:9 宽高比的视频播放区域
extends AspectRatioContainer

func _ready():
    ratio = 16.0 / 9.0  # 宽高比 16:9
    stretch_mode = AspectRatioContainer.StretchModeEnum.FIT  # 等比适配
    alignment_horizontal = AspectRatioContainer.AlignmentMode.CENTER
    alignment_vertical = AspectRatioContainer.AlignmentMode.CENTER

    size = Vector2(640, 480)  # 容器可以任意大小，内容始终保持比例

    # 里面放一张图片作为示例（实际可能是 VideoStreamPlayer）
    var image = TextureRect.new()
    image.texture = load("res://icon.svg")
    image.stretch_mode = TextureRect.StretchModeEnum.KEEP_ASPECT_CENTERED
    image.expand_mode = TextureRect.ExpandModeEnum.IGNORE_SIZE
    add_child(image)