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

PopupMenu

节点继承关系

继承链：Node → CanvasItem → Control → PopupMenu

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

定义

PopupMenu 是一个弹出式菜单——就是那种右键点击后弹出的选项列表，或者点击按钮后出现的小菜单。就像你在桌面右键点击弹出的"刷新、复制、粘贴"那种菜单。MenuButton 内部就使用了一个 PopupMenu 来显示菜单项。

使用频率：★★ 偶尔使用（右键菜单、下拉菜单等）

节点用途

• 右键上下文菜单
• 下拉选项菜单
• 作为 MenuButton 的内部菜单

使用场景

• 游戏中右键点击物品弹出的操作菜单
• 自定义的上下文菜单
• 快捷操作菜单

常用节点搭配

• MenuButton 内部自动创建
• 搭配 Button 触发弹出

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
item_count	int	0	—	菜单项总数（只读）

信号

信号	触发时机	参数
id_pressed	点击菜单项时	int 菜单项 ID
index_pressed	点击菜单项时（按索引）	int 菜单项索引

常用方法

方法	说明
AddItem("文字", id)	添加一个菜单项
AddSeparator()	添加分隔线
AddCheckItem("文字", id)	添加可勾选菜单项
AddRadioCheckItem("文字", id)	添加单选菜单项
RemoveItem(index)	移除指定菜单项
Clear()	清空所有菜单项
Popup(Rect2)	在指定位置弹出
PopupCentered()	在屏幕中央弹出
IsItemChecked(index)	判断菜单项是否被勾选
SetItemChecked(index, bool)	设置菜单项勾选状态

代码示例

C

using Godot;

public partial class RightClickMenu : Control
{
    private PopupMenu _popupMenu;

    public override void _Ready()
    {
        _popupMenu = new PopupMenu();
        _popupMenu.AddItem("使用", 0);
        _popupMenu.AddItem("丢弃", 1);
        _popupMenu.AddSeparator();
        _popupMenu.AddItem("查看详情", 2);
        _popupMenu.AddItem("取消", 3);

        _popupMenu.IdPressed += (id) =>
        {
            switch (id)
            {
                case 0: GD.Print("使用物品"); break;
                case 1: GD.Print("丢弃物品"); break;
                case 2: GD.Print("查看详情"); break;
            }
        };

        AddChild(_popupMenu);
    }

    public override void _GuiInput(InputEvent @event)
    {
        if (@event is InputEventMouseButton { Pressed: true, ButtonIndex: MouseButton.Right } mb)
        {
            _popupMenu.Popup(new Rect2I((Vector2I)mb.GlobalPosition, new Vector2I(0, 0)));
        }
    }
}

GDScript

extends Control

var popup_menu: PopupMenu

func _ready():
    popup_menu = PopupMenu.new()
    popup_menu.add_item("使用", 0)
    popup_menu.add_item("丢弃", 1)
    popup_menu.add_separator()
    popup_menu.add_item("查看详情", 2)
    popup_menu.add_item("取消", 3)

    popup_menu.id_pressed.connect(func(id: int):
        match id:
            0: print("使用物品")
            1: print("丢弃物品")
            2: print("查看详情")
    )

    add_child(popup_menu)

func _gui_input(event: InputEvent):
    if event is InputEventMouseButton and event.pressed and event.button_index == MOUSE_BUTTON_RIGHT:
        popup_menu.popup(Rect2i(Vector2i(event.global_position), Vector2i(0, 0)))