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

SubViewportContainer

节点继承关系

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

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()	获取父节点

定义

SubViewportContainer 用来在 UI 界面中嵌入一个 SubViewport（子视口）。它的工作方式是：你把一个 SubViewport 节点放进去，然后 SubViewport 里面可以放任何 2D 或 3D 场景，渲染结果会直接显示在 SubViewportContainer 的区域内。就像在一个 UI 面板上开了一个"窗口"，透过这个窗口可以看到另一个场景。

使用频率：★★ 偶尔使用（小地图、3D 预览等专项使用）

节点用途

• 小地图显示
• 3D 角色预览窗口
• 嵌入另一个场景的渲染结果

使用场景

• 角色选择界面的 3D 角色预览
• 游戏内小地图
• 画中画效果

常用节点搭配

• 必须包含 SubViewport 子节点
• SubViewport 内放 2D 或 3D 场景

生效必备素材/资源

无需特殊资源。需要搭配 SubViewport 使用。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
stretch	bool	true	—	是否拉伸子视口内容以匹配容器大小
stretch_shrink	float	1.0	—	拉伸时的缩小比例

信号

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

常用方法

继承自 Container 的所有方法。

代码示例

C

using Godot;

// 3D 角色预览窗口
public partial class CharacterPreview : Control
{
    public override void _Ready()
    {
        // 创建 SubViewportContainer
        var vpContainer = new SubViewportContainer();
        vpContainer.Stretch = true;
        vpContainer.Size = new Vector2(300, 300);
        vpContainer.Position = new Vector2(50, 50);
        AddChild(vpContainer);

        // 创建 SubViewport
        var viewport = new SubViewport();
        viewport.Size = new Vector2(300, 300);
        viewport.TransparentBg = true;
        vpContainer.AddChild(viewport);

        // 在 SubViewport 中放一个 Camera3D
        var camera = new Camera3D();
        camera.Position = new Vector3(0, 1, 3);
        camera.LookAt(new Vector3(0, 1, 0), Vector3.Up);
        viewport.AddChild(camera);

        // 在 SubViewport 中放一个场景（比如一个 3D 模型）
        var worldRoot = new Node3D();
        viewport.AddChild(worldRoot);
    }
}

GDScript

# 3D 角色预览窗口
extends Control

func _ready():
    # 创建 SubViewportContainer
    var vp_container = SubViewportContainer.new()
    vp_container.stretch = true
    vp_container.size = Vector2(300, 300)
    vp_container.position = Vector2(50, 50)
    add_child(vp_container)

    # 创建 SubViewport
    var viewport = SubViewport.new()
    viewport.size = Vector2(300, 300)
    viewport.transparent_bg = true
    vp_container.add_child(viewport)

    # 在 SubViewport 中放一个 Camera3D
    var camera = Camera3D.new()
    camera.position = Vector3(0, 1, 3)
    camera.look_at(Vector3(0, 1, 0), Vector3.UP)
    viewport.add_child(camera)

    # 在 SubViewport 中放一个场景（比如一个 3D 模型）
    var world_root = Node3D.new()
    viewport.add_child(world_root)