Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

GraphEdit

繼承： Control < CanvasItem < Node < Object

圖結構編輯器，使用 GraphNode。

說明

GraphEdit 提供了用於對各種圖進行建立、操作、顯示的工具。它在引擎中的主要目的是驅動視覺化編程系統，例如視覺化著色器，但也可以在使用者專案中使用。

GraphEdit 本身只是一個空容器，表示一個可以放置 GraphNode 的無限柵格。每個 GraphNode 代表圖中的一個節點，是連接方案中的單個資料單元。而 GraphEdit 則有助於控制節點和節點之間的各種互動。當使用者嘗試連接、斷開或刪除一個 GraphNode 時，GraphEdit 中會發出對應的訊號，但預設情況下不執行任何動作。使用此控制項的程式設計師負責實作必要的邏輯，來確定應如何處理每個請求。

效能：強烈建議在使用 GraphEdit 時啟用低處理器使用模式（見 OS.low_processor_usage_mode）。

注意：請注意，由於技術限制，Node.get_children() 還將回傳名為 _connection_layer 的連接層節點。該行為可能會在未來版本中發生變化。

屬性

bool

clip_contents

true (overrides Control)

bool

connection_lines_antialiased

true

float

connection_lines_curvature

0.5

float

connection_lines_thickness

4.0

Array[Dictionary]

connections

[]

FocusMode

focus_mode

2 (overrides Control)

GridPattern

grid_pattern

0

bool

minimap_enabled

true

float

minimap_opacity

0.65

Vector2

minimap_size

Vector2(240, 160)

PanningScheme

panning_scheme

0

bool

right_disconnects

false

Vector2

scroll_offset

Vector2(0, 0)

bool

show_arrange_button

true

bool

show_grid

true

bool

show_grid_buttons

true

bool

show_menu

true

bool

show_minimap_button

true

bool

show_zoom_buttons

true

bool

show_zoom_label

false

int

snapping_distance

20

bool

snapping_enabled

true

Dictionary

type_names

{}

float

zoom

1.0

float

zoom_max

2.0736003

float

zoom_min

0.23256795

float

zoom_step

1.2

方法

PackedVector2Array

_get_connection_line(from_position: Vector2, to_position: Vector2) virtual const

bool

_is_in_input_hotzone(in_node: Object, in_port: int, mouse_position: Vector2) virtual

bool

_is_in_output_hotzone(in_node: Object, in_port: int, mouse_position: Vector2) virtual

bool

_is_node_hover_valid(from_node: StringName, from_port: int, to_node: StringName, to_port: int) virtual

void

add_valid_connection_type(from_type: int, to_type: int)

void

add_valid_left_disconnect_type(type: int)

void

add_valid_right_disconnect_type(type: int)

void

arrange_nodes()

void

attach_graph_element_to_frame(element: StringName, frame: StringName)

void

clear_connections()

Error

connect_node(from_node: StringName, from_port: int, to_node: StringName, to_port: int, keep_alive: bool = false)

void

detach_graph_element_from_frame(element: StringName)

void

disconnect_node(from_node: StringName, from_port: int, to_node: StringName, to_port: int)

void

force_connection_drag_end()

Array[StringName]

get_attached_nodes_of_frame(frame: StringName)

Dictionary

get_closest_connection_at_point(point: Vector2, max_distance: float = 4.0) const

int

get_connection_count(from_node: StringName, from_port: int)

PackedVector2Array

get_connection_line(from_node: Vector2, to_node: Vector2) const

Array[Dictionary]

get_connection_list_from_node(node: StringName) const

Array[Dictionary]

get_connections_intersecting_with_rect(rect: Rect2) const

GraphFrame

get_element_frame(element: StringName)

HBoxContainer

get_menu_hbox()

bool

is_node_connected(from_node: StringName, from_port: int, to_node: StringName, to_port: int)

bool

is_valid_connection_type(from_type: int, to_type: int) const

void

remove_valid_connection_type(from_type: int, to_type: int)

void

remove_valid_left_disconnect_type(type: int)

void

remove_valid_right_disconnect_type(type: int)

void

set_connection_activity(from_node: StringName, from_port: int, to_node: StringName, to_port: int, amount: float)

void

set_selected(node: Node)

主題屬性

Color

activity

Color(1, 1, 1, 1)

Color

connection_hover_tint_color

Color(0, 0, 0, 0.3)

Color

connection_rim_color

Color(0.1, 0.1, 0.1, 0.6)

Color

connection_valid_target_tint_color

Color(1, 1, 1, 0.4)

Color

grid_major

Color(1, 1, 1, 0.2)

Color

grid_minor

Color(1, 1, 1, 0.05)

Color

selection_fill

Color(1, 1, 1, 0.3)

Color

selection_stroke

Color(1, 1, 1, 0.8)

int

connection_hover_thickness

0

int

port_hotzone_inner_extent

22

int

port_hotzone_outer_extent

26

Texture2D

grid_toggle

Texture2D

layout

Texture2D

minimap_toggle

Texture2D

snapping_toggle

Texture2D

zoom_in

Texture2D

zoom_out

Texture2D

zoom_reset

StyleBox

menu_panel

StyleBox

panel

StyleBox

panel_focus

訊號

begin_node_move() 🔗

在 GraphElement 移動開始時發出。

connection_drag_ended() 🔗

在連接拖動結束時發出。

connection_drag_started(from_node: StringName, from_port: int, is_output: bool) 🔗

在連接拖動開始時發出。

connection_from_empty(to_node: StringName, to_port: int, release_position: Vector2) 🔗

當使用者將連接從輸入埠拖動到圖形的空白區域時發出。

connection_request(from_node: StringName, from_port: int, to_node: StringName, to_port: int) 🔗

當嘗試建立 from_node GraphNode 的 from_port 和 to_node GraphNode 的 to_port 之間的連接時發出。

connection_to_empty(from_node: StringName, from_port: int, release_position: Vector2) 🔗

當使用者將連接從輸出埠拖動到圖形的空白區域時發出。

copy_nodes_request() 🔗

當該 GraphEdit 捕獲 ui_copy 動作（預設情況下為 Ctrl + C）時發出。一般來說，該訊號指示所選的 GraphElement 應被複製。

cut_nodes_request() 🔗

當該 GraphEdit 捕獲 ui_cut 動作（預設情況下為 Ctrl + X）時發出。一般來說，該訊號指示所選的 GraphElement 應被剪切。

delete_nodes_request(nodes: Array[StringName]) 🔗

當該 GraphEdit 捕獲 ui_graph_delete 動作（預設為 Delete）時觸發。

nodes 是應被移除的節點的名稱的陣列。這些通常包括所有選定的節點。

disconnection_request(from_node: StringName, from_port: int, to_node: StringName, to_port: int) 🔗

當試圖移除 from_node GraphNode 的 from_port 和 to_node GraphNode 的 to_port 之間的連接時發出。

duplicate_nodes_request() 🔗

當該 GraphEdit 捕獲 ui_graph_duplicate 動作（預設為 Ctrl + D）時觸發。一般來說，該訊號指示應被複製的所選的 GraphElement。

end_node_move() 🔗

在 GraphElement 移動結束時發出。

frame_rect_changed(frame: GraphFrame, new_rect: Rect2) 🔗

當 GraphFrame frame 大小調整為 new_rect 時發出。

graph_elements_linked_to_frame_request(elements: Array, frame: StringName) 🔗

當一個或多個 GraphElement 被放到名為 frame 的 GraphFrame 上，且它們之前未被附加到任何其他框中時發出。

elements 是要附加的 GraphElement 陣列。

node_deselected(node: Node) 🔗

當給定的 GraphElement 節點被取消選擇時發出。

node_selected(node: Node) 🔗

當給定的 GraphElement 節點被選中時發出。

paste_nodes_request() 🔗

當該 GraphEdit 捕獲 ui_paste 動作（預設為 Ctrl + V）時觸發。一般來說，該訊號指示應被貼上的先前複製的 GraphElement。

popup_request(at_position: Vector2) 🔗

當請求彈出視窗時發出。在 GraphEdit 中右鍵點選時發生。at_position為該訊號被發出時滑鼠指針的位置。

scroll_offset_changed(offset: Vector2) 🔗

當使用者改變捲動偏移量時發出。在程式碼中改變捲動偏移量時，它不會被觸發。

列舉

enum PanningScheme: 🔗

PanningScheme SCROLL_ZOOMS = 0

滑鼠滾輪進行縮放，Ctrl + 滑鼠滾輪進行視圖的移動。

PanningScheme SCROLL_PANS = 1

滑鼠滾輪進行視圖的移動，Ctrl + 滑鼠滾輪進行縮放。

enum GridPattern: 🔗

GridPattern GRID_PATTERN_LINES = 0

使用實線繪製網格。

GridPattern GRID_PATTERN_DOTS = 1

使用點線繪製網格。

屬性說明

bool connection_lines_antialiased = true 🔗

  • void set_connection_lines_antialiased(value: bool)

  • bool is_connection_lines_antialiased()

如果為 true，節點之間的線將使用反鋸齒。

float connection_lines_curvature = 0.5 🔗

  • void set_connection_lines_curvature(value: float)

  • float get_connection_lines_curvature()

節點之間連線的曲率。0 得到的是直線。

float connection_lines_thickness = 4.0 🔗

  • void set_connection_lines_thickness(value: float)

  • float get_connection_lines_thickness()

節點之間連線的粗細。

Array[Dictionary] connections = [] 🔗

GraphNode 之間的連接。

連接由 Dictionary 代表，形式為：

{
    from_node: StringName,
    from_port: int,
    to_node: StringName,
    to_port: int,
    keep_alive: bool
}

重繪時，如果 keep_alive 為 false 的連接無效，則可能會被自動刪除。

GridPattern grid_pattern = 0 🔗

繪製網格時使用的圖案。

bool minimap_enabled = true 🔗

  • void set_minimap_enabled(value: bool)

  • bool is_minimap_enabled()

如果為 true，小圖是可見的。

float minimap_opacity = 0.65 🔗

  • void set_minimap_opacity(value: float)

  • float get_minimap_opacity()

小圖矩形的不透明度。

Vector2 minimap_size = Vector2(240, 160) 🔗

小圖矩形的大小。地圖自身基於網格區域的大小，並被縮放以適應這個矩形。

PanningScheme panning_scheme = 0 🔗

定義使用滑鼠滾輪平移的控制方案。

bool right_disconnects = false 🔗

  • void set_right_disconnects(value: bool)

  • bool is_right_disconnects_enabled()

如果為 true，通過拖動右端，可以斷開 GraphEdit 中現有的連接。

Vector2 scroll_offset = Vector2(0, 0) 🔗

捲動偏移量。

bool show_arrange_button = true 🔗

  • void set_show_arrange_button(value: bool)

  • bool is_showing_arrange_button()

如果為 true，控制項將自動調整高度以適合其內容。

bool show_grid = true 🔗

  • void set_show_grid(value: bool)

  • bool is_showing_grid()

如果為 true，則該視窗可見。

bool show_grid_buttons = true 🔗

  • void set_show_grid_buttons(value: bool)

  • bool is_showing_grid_buttons()

如果為 true，則停用形狀所有者及其形狀。

bool show_menu = true 🔗

  • void set_show_menu(value: bool)

  • bool is_showing_menu()

如果為 true，小圖是可見的。

bool show_minimap_button = true 🔗

  • void set_show_minimap_button(value: bool)

  • bool is_showing_minimap_button()

如果為 true，小圖是可見的。

bool show_zoom_buttons = true 🔗

  • void set_show_zoom_buttons(value: bool)

  • bool is_showing_zoom_buttons()

如果為 true，則色板和近期顏色預設可見。

bool show_zoom_label = false 🔗

  • void set_show_zoom_label(value: bool)

  • bool is_showing_zoom_label()

如果為 true，則使目前縮放級別的標籤可見。縮放值以百分比顯示。

int snapping_distance = 20 🔗

  • void set_snapping_distance(value: int)

  • int get_snapping_distance()

吸附距離，單位為圖元。

bool snapping_enabled = true 🔗

  • void set_snapping_enabled(value: bool)

  • bool is_snapping_enabled()

如果為 true，啟用自動吸附。

Dictionary type_names = {} 🔗

包含人類可讀連接埠型別名稱的 Dictionary。

float zoom = 1.0 🔗

目前縮放值。

float zoom_max = 2.0736003 🔗

  • void set_zoom_max(value: float)

  • float get_zoom_max()

縮放上限。

float zoom_min = 0.23256795 🔗

  • void set_zoom_min(value: float)

  • float get_zoom_min()

縮放下限。

float zoom_step = 1.2 🔗

  • void set_zoom_step(value: float)

  • float get_zoom_step()

每個縮放級別的步長。

方法說明

PackedVector2Array _get_connection_line(from_position: Vector2, to_position: Vector2) virtual const 🔗

可以重寫的虛方法，以自訂如何繪製連接。

bool _is_in_input_hotzone(in_node: Object, in_port: int, mouse_position: Vector2) virtual 🔗

回傳 mouse_position 是否在輸入熱區。

預設情況下，熱區是一個 Rect2，其中心位於 in_node.GraphNode.get_input_port_position()(in_port)（對於輸出的情況，請改為呼叫 GraphNode.get_output_port_position()）。熱區的寬度是主題屬性 port_grab_distance_horizontal 的兩倍，高度是 port_grab_distance_vertical 的兩倍。

下面是一個範例程式碼，以協助入門：

func _is_in_input_hotzone(in_node, in_port, mouse_position):
    var port_size = Vector2(get_theme_constant("port_grab_distance_horizontal"), get_theme_constant("port_grab_distance_vertical"))
    var port_pos = in_node.get_position() + in_node.get_input_port_position(in_port) - port_size / 2
    var rect = Rect2(port_pos, port_size)

    return rect.has_point(mouse_position)

bool _is_in_output_hotzone(in_node: Object, in_port: int, mouse_position: Vector2) virtual 🔗

回傳 mouse_position 是否在輸出熱區。有關熱區的更多資訊，請參閱 _is_in_input_hotzone()。

下面是一個範例程式碼，以協助入門：

func _is_in_output_hotzone(in_node, in_port, mouse_position):
    var port_size = Vector2(get_theme_constant("port_grab_distance_horizontal"), get_theme_constant("port_grab_distance_vertical"))
    var port_pos = in_node.get_position() + in_node.get_output_port_position(in_port) - port_size / 2
    var rect = Rect2(port_pos, port_size)

    return rect.has_point(mouse_position)

bool _is_node_hover_valid(from_node: StringName, from_port: int, to_node: StringName, to_port: int) virtual 🔗

當使用者在有效埠上拖動連接時，該虛擬方法可用於插入額外的錯誤偵測。

如果連接確實有效，則返回 true；如果連接不可能，則返回 false。如果連接是不可能的，則不會捕捉到該埠，因此不會發起對該埠的連接請求。

在該範例中，抑制了與同一節點的連接：

func _is_node_hover_valid(from, from_port, to, to_port):
    return from != to

void add_valid_connection_type(from_type: int, to_type: int) 🔗

允許兩種不同埠型別之間的連接。埠型別是使用 GraphNode.set_slot() 方法為每個插槽的左右埠單獨定義的。

另請參閱 is_valid_connection_type() 和 remove_valid_connection_type()。

void add_valid_left_disconnect_type(type: int) 🔗

如果 GraphNode 插槽的左側埠具有指定的型別，則允許在從該埠拖動時斷開節點。另請參閱 remove_valid_left_disconnect_type()。

void add_valid_right_disconnect_type(type: int) 🔗

如果 GraphNode 插槽的右側埠具有指定的型別，則允許在從該埠拖動時斷開節點。另請參閱 remove_valid_right_disconnect_type()。

void arrange_nodes() 🔗

重新排列佈局中的選定節點，使連接之間的交叉最少，節點之間的水平和垂直間隙保持一致。

void attach_graph_element_to_frame(element: StringName, frame: StringName) 🔗

將 element GraphElement 附加到 frame GraphFrame。

void clear_connections() 🔗

移除節點之間的所有連接。

Error connect_node(from_node: StringName, from_port: int, to_node: StringName, to_port: int, keep_alive: bool = false) 🔗

在來源 GraphNode 節點 from_node 的 from_port 連接埠和目標 GraphNode 節點 to_node 的 to_port 連接埠之間建立連接。如果已存在連接，則不會建立連接。

keep_alive 為 false 的連接如果在重繪期間失效，則可能會被自動刪除。

void detach_graph_element_from_frame(element: StringName) 🔗

將 element GraphElement 從其目前附加的 GraphFrame 中分離出來。

void disconnect_node(from_node: StringName, from_port: int, to_node: StringName, to_port: int) 🔗

移除 from_node GraphNode 的 from_port 和 to_node GraphNode 的 to_port 之間的連接。如果該連接不存在，則不移除任何連接。

void force_connection_drag_end() 🔗

結束目前連接的建立。換句話說，如果正在拖動一個連接，可以使用該方法中止該過程，並移除滑鼠游標後面的線。

這最好與 connection_drag_started 和 connection_drag_ended 一起使用，以新增自訂的行為，如通過快捷方式新增節點。

注意：該方法會抑制除 connection_drag_ended 之外的任何其他連接請求訊號。

Array[StringName] get_attached_nodes_of_frame(frame: StringName) 🔗

回傳附加到給定名稱的 GraphFrame 的節點名稱陣列。

Dictionary get_closest_connection_at_point(point: Vector2, max_distance: float = 4.0) const 🔗

回傳到螢幕空間中給定點的最近連接。如果在 max_distance 像素內未找到連接，則回傳空的 Dictionary。

連接由以下形式的結構組成：

{
    from_node: StringName,
    from_port: int,
    to_node: StringName,
    to_port: int,
    keep_alive: bool
}

例如，可以像這樣實現取得在給定滑鼠位置處的連接：

var connection = get_closest_connection_at_point(mouse_event.get_position())

int get_connection_count(from_node: StringName, from_port: int) 🔗

回傳 from_node 節點的 from_port 連接埠的連接數量。

PackedVector2Array get_connection_line(from_node: Vector2, to_node: Vector2) const 🔗

返回構成 from_node 和 to_node 之間的連接的點。

Array[Dictionary] get_connection_list_from_node(node: StringName) const 🔗

回傳包含 node 節點所有連接的 Array。

連接使用 Dictionary 表示，形式為：

{
    from_node: StringName,
    from_port: int,
    to_node: StringName,
    to_port: int,
    keep_alive: bool
}

範例：取得指定連接埠的所有連接：

func get_connection_list_from_port(node, port):
    var connections = get_connection_list_from_node(node)
    var result = []
    for connection in connections:
        var dict = {}
        if connection["from_node"] == node and connection["from_port"] == port:
            dict["node"] = connection["to_node"]
            dict["port"] = connection["to_port"]
            dict["type"] = "left"
            result.push_back(dict)
        elif connection["to_node"] == node and connection["to_port"] == port:
            dict["node"] = connection["from_node"]
            dict["port"] = connection["from_port"]
            dict["type"] = "right"
            result.push_back(dict)
    return result

Array[Dictionary] get_connections_intersecting_with_rect(rect: Rect2) const 🔗

回傳一個 Array，其中包含與給定 Rect2 相交的連接清單。

連接由 Dictionary 表示，結構如下：

{
    from_node: StringName,
    from_port: int,
    to_node: StringName,
    to_port: int,
    keep_alive: bool
}

GraphFrame get_element_frame(element: StringName) 🔗

回傳包含給定名稱的 GraphElement 的 GraphFrame。

HBoxContainer get_menu_hbox() 🔗

取得包含圖形左上角的縮放和網格捕捉控制項的 HBoxContainer。你可以使用此方法重新定位工具列或向其新增自訂控制項。

警告：這是一個必需的內部節點，刪除和釋放它可能會導致當機。如果你希望隱藏它或其任何子項，請使用它們的 CanvasItem.visible 屬性。

bool is_node_connected(from_node: StringName, from_port: int, to_node: StringName, to_port: int) 🔗

如果 from_node GraphNode 的 from_port 連接到 to_node GraphNode 的 to_port，則返回 true。

bool is_valid_connection_type(from_type: int, to_type: int) const 🔗

返回是否可以在兩種不同的埠型別之間建立連接。埠型別是使用 GraphNode.set_slot() 方法為每個插槽的左右埠單獨定義的。

另請參閱 add_valid_connection_type() 和 remove_valid_connection_type()。

void remove_valid_connection_type(from_type: int, to_type: int) 🔗

不允許先前由 add_valid_connection_type() 允許的兩種不同埠型別之間的連接。埠型別是通過 GraphNode.set_slot() 方法為每個插槽的左右埠單獨定義的。

另請參閱 is_valid_connection_type()。

void remove_valid_left_disconnect_type(type: int) 🔗

如果 GraphNode 插槽的左側連接埠具有指定型別，當從該連接埠拖動時，則不允許斷開節點的連接。使用該方法來停用以前使用 add_valid_left_disconnect_type() 允許的斷開連接。

void remove_valid_right_disconnect_type(type: int) 🔗

如果 GraphNode 插槽的右側連接埠具有指定型別，當從該連接埠拖動時，則不允許斷開節點的連接。使用該方法來停用以前使用 add_valid_right_disconnect_type() 允許的斷開連接。

void set_connection_activity(from_node: StringName, from_port: int, to_node: StringName, to_port: int, amount: float) 🔗

使用 activity 主題屬性中提供的顏色，設定 from_node 的 from_port 和 to_node 的 to_port 之間的連接的顏色。使用 amount 作為權重，在連接顏色和活動顏色之間線性插值顏色。

void set_selected(node: Node) 🔗

將指定的 node 節點設定為選中的節點。

主題屬性說明

Color activity = Color(1, 1, 1, 1) 🔗

根據連接的活動值插入連接線的顏色（請參閱 set_connection_activity()）。

Color connection_hover_tint_color = Color(0, 0, 0, 0.3) 🔗

當滑鼠懸停在連接線上時與該連接線混合的顏色。

Color connection_rim_color = Color(0.1, 0.1, 0.1, 0.6) 🔗

每條連接線周圍的邊緣顏色，用於使相交線更容易區分。

Color connection_valid_target_tint_color = Color(1, 1, 1, 0.4) 🔗

目前拖動的連接懸停在有效目標連接埠上時與該連接線混合的顏色。

Color grid_major = Color(1, 1, 1, 0.2) 🔗

主要柵格線/點的顏色。

Color grid_minor = Color(1, 1, 1, 0.05) 🔗

次要柵格線/點的顏色。

Color selection_fill = Color(1, 1, 1, 0.3) 🔗

選定的矩形的填充顏色。

Color selection_stroke = Color(1, 1, 1, 0.8) 🔗

選擇的矩形的輪廓顏色。

int connection_hover_thickness = 0 🔗

滑鼠懸停在連接上時，按百分比係數加寬連接的線條。取值為 0 會停用醒目標示。取值為 100 會將線寬加倍。

int port_hotzone_inner_extent = 22 🔗

能夠抓取埠的（內側）橫向範圍。

int port_hotzone_outer_extent = 26 🔗

能夠抓取埠的（外側）橫向範圍。

Texture2D grid_toggle 🔗

吸附動按鈕的圖示。

Texture2D layout 🔗

關閉按鈕被按下時的圖示。

Texture2D minimap_toggle 🔗

吸附動按鈕的圖示。

Texture2D snapping_toggle 🔗

吸附動按鈕的圖示。

Texture2D zoom_in 🔗

放大按鈕的圖示。

Texture2D zoom_out 🔗

縮小按鈕的圖示。

Texture2D zoom_reset 🔗

縮放重新開機按鈕的圖示。

StyleBox menu_panel 🔗

There is currently no description for this theme property. Please help us by contributing one!

StyleBox panel 🔗

繪製在柵格下方的背景。

StyleBox panel_focus 🔗

當 GraphEdit 處於聚焦狀態時使用的 StyleBox（使用輔助應用時）。