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

GraphEdit

节点继承关系

继承链：Node → CanvasItem → Control → GraphEdit

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

定义

GraphEdit 提供一个画布，上面可以放置多个节点（GraphNode），节点之间可以连线。适合做蓝图编辑器、对话编辑器、技能树编辑器等。就像 Unreal 的蓝图编辑器或者 Godot 自己的可视化脚本编辑器——一个可以拖拽节点和连线的画布。

使用频率：★ 基本用不到（做编辑器类工具时才用）

节点用途

• 制作节点图编辑器
• 蓝图/可视化脚本系统
• 对话树编辑器

使用场景

• 游戏内置的关卡逻辑编辑器
• 对话系统编辑器
• 技能树可视化编辑

常用节点搭配

• 搭配 GraphNode（非 UI 节点，放在 GraphEdit 内）做节点卡片

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
zoom	float	1.0	—	缩放比例
zoom_min	float	0.25	—	最小缩放
zoom_max	float	2.0	—	最大缩放
zoom_step	float	0.1	—	每次缩放的步进值
scroll_offset	Vector2	(0, 0)	—	滚动偏移
snapping_enabled	bool	false	—	是否启用网格吸附
snapping_distance	int	20	—	吸附距离

信号

信号	触发时机	参数
connection_request	请求连线时	string 源节点, int 源端口, string 目标节点, int 目标端口
disconnection_request	请求断开连线时	string 源节点, int 源端口, string 目标节点, int 目标端口
node_selected	选中节点时	Node 被选中的节点
node_deselected	取消选中节点时	Node 被取消的节点

常用方法

方法	说明
AddChild(node)	添加 GraphNode 子节点
ZoomChanged += handler	监听缩放变化
SetZoom(float)	设置缩放比例
GetScrollOffset()	获取滚动偏移

代码示例

C

using Godot;

public partial class DialogEditor : GraphEdit
{
    public override void _Ready()
    {
        Size = new Vector2(800, 600);
        SnappingEnabled = true;
        SnappingDistance = 20;

        // 监听连线请求
        ConnectionRequest += OnConnectionRequest;

        // 添加一些节点（GraphNode 需要在编辑器中创建或代码中构建）
        var nodeA = new GraphNode();
        nodeA.Title = "开始";
        nodeA.PositionOffset = new Vector2(100, 100);
        nodeA.SizeOffset = new Vector2(150, 50);
        var labelA = new Label() { Text = "你好，冒险者！" };
        nodeA.AddChild(labelA);
        AddChild(nodeA);

        var nodeB = new GraphNode();
        nodeB.Title = "选择";
        nodeB.PositionOffset = new Vector2(400, 100);
        nodeB.SizeOffset = new Vector2(150, 80);
        var labelB = new Label() { Text = "接受任务？" };
        nodeB.AddChild(labelB);
        AddChild(nodeB);
    }

    private void OnConnectionRequest(string fromNode, int fromPort, string toNode, int toPort)
    {
        GD.Print($"连线: {fromNode} 端口 {fromPort} -> {toNode} 端口 {toPort}");
        ConnectNode(fromNode, fromPort, toNode, toPort);
    }
}

GDScript

extends GraphEdit

func _ready():
    size = Vector2(800, 600)
    snapping_enabled = true
    snapping_distance = 20

    # 监听连线请求
    connection_request.connect(_on_connection_request)

    # 添加一些节点
    var node_a = GraphNode.new()
    node_a.title = "开始"
    node_a.position_offset = Vector2(100, 100)
    node_a.size_offset = Vector2(150, 50)
    var label_a = Label.new()
    label_a.text = "你好，冒险者！"
    node_a.add_child(label_a)
    add_child(node_a)

    var node_b = GraphNode.new()
    node_b.title = "选择"
    node_b.position_offset = Vector2(400, 100)
    node_b.size_offset = Vector2(150, 80)
    var label_b = Label.new()
    label_b.text = "接受任务？"
    node_b.add_child(label_b)
    add_child(node_b)

func _on_connection_request(from_node: String, from_port: int, to_node: String, to_port: int):
    print("连线: " + from_node + " 端口 " + str(from_port) + " -> " + to_node + " 端口 " + str(to_port))
    connect_node(from_node, from_port, to_node, to_port)