跳转至

GFDropZone

API Reference / Standard / 类索引

  • 路径：addons/gf/standard/input/drag_drop/gf_drop_zone.gd
  • 模块：Standard
  • 继承：RefCounted
  • API：public
  • 类别：领域模型 (domain_model)
  • 首次版本：3.17.0

通用拖拽落点规则。 落点只描述“某个位置是否命中、某个会话是否可接收、接收时如何返回结果”。 它不移动节点、不修改业务数据，也不规定任何具体 UI 或玩法语义。

成员概览

类型 名称 签名
属性 zone_id var zone_id: StringName = &""
属性 accepted_types var accepted_types: PackedStringArray = PackedStringArray()
属性 priority var priority: int = 0
属性 enabled var enabled: bool = true
属性 contains_callable var contains_callable: Callable = Callable()
属性 can_accept_callable var can_accept_callable: Callable = Callable()
属性 drop_callable var drop_callable: Callable = Callable()
属性 metadata var metadata: Dictionary = {}
方法 contains func contains(position: Variant, session: GFDragSession) -> bool:
方法 can_accept func can_accept(session: GFDragSession) -> bool:
方法 drop func drop(session: GFDragSession, position: Variant) -> Variant:
方法 to_dictionary func to_dictionary() -> Dictionary:
方法 from_rect static func from_rect( new_zone_id: StringName, rect: Rect2, new_accepted_types: PackedStringArray = PackedStringArray(), options: Dictionary = {} ) -> GFDropZone:
方法 from_control static func from_control( new_zone_id: StringName, control: Control, new_accepted_types: PackedStringArray = PackedStringArray(), options: Dictionary = {} ) -> GFDropZone:

属性

zone_id

  • API：public
var zone_id: StringName = &""

落点 ID。

accepted_types

  • API：public
var accepted_types: PackedStringArray = PackedStringArray()

可接收的拖拽类型。为空表示不限制类型。

priority

  • API：public
var priority: int = 0

匹配优先级。数值越大越优先。

enabled

  • API：public
var enabled: bool = true

是否启用。

contains_callable

  • API：public
var contains_callable: Callable = Callable()

命中检测回调，签名为 func(position: Variant, session: GFDragSession) -> bool。

can_accept_callable

  • API：public
var can_accept_callable: Callable = Callable()

可接收检测回调，签名为 func(session: GFDragSession, zone: GFDropZone) -> bool。

drop_callable

  • API：public
var drop_callable: Callable = Callable()

接收回调，签名为 func(session: GFDragSession, zone: GFDropZone, position: Variant) -> Variant。

metadata

  • API：public
var metadata: Dictionary = {}

项目自定义元数据。框架不解释该字段。

结构：

  • metadata: Dictionary，关联到 drop zone 的项目侧元数据。

方法

contains

  • API：public
func contains(position: Variant, session: GFDragSession) -> bool:

检查落点是否包含位置。

参数：

名称 说明
position 位置，通常是屏幕或画布坐标。
session 当前拖拽会话。

返回：命中时返回 true。

结构：

  • position: Variant，zone contains 回调接受的位置值。

can_accept

  • API：public
func can_accept(session: GFDragSession) -> bool:

检查落点是否接收会话。

参数：

名称 说明
session 当前拖拽会话。

返回：可接收时返回 true。

drop

  • API：public
func drop(session: GFDragSession, position: Variant) -> Variant:

执行落点接收回调。

参数：

名称 说明
session 当前拖拽会话。
position 释放位置。

返回：回调返回值；未设置回调时返回成功字典。

结构：

  • position: Variant release position passed to the drop callback.
  • return: Variant，由 drop 回调返回；Dictionary 会由 GFDragDropUtility 规范化。

to_dictionary

  • API：public
func to_dictionary() -> Dictionary:

转换为调试字典。

返回：落点快照。

结构：

  • return: Dictionary，包含 zone_id、accepted_types、priority、enabled、回调标记和 metadata。

from_rect

  • API：public
static func from_rect( new_zone_id: StringName, rect: Rect2, new_accepted_types: PackedStringArray = PackedStringArray(), options: Dictionary = {} ) -> GFDropZone:

创建矩形落点。

参数：

名称 说明
new_zone_id 落点 ID。
rect 全局矩形区域。
new_accepted_types 可接收类型；为空表示不限制。
options 可选参数，支持 priority、enabled、metadata、can_accept、drop。

返回：新落点。

结构：

  • options: Dictionary，包含 priority: int、enabled: bool、metadata: Dictionary、can_accept: Callable 和 drop: Callable。

from_control

  • API：public
static func from_control( new_zone_id: StringName, control: Control, new_accepted_types: PackedStringArray = PackedStringArray(), options: Dictionary = {} ) -> GFDropZone:

创建 Control 全局矩形落点。

参数：

名称 说明
new_zone_id 落点 ID。
control 用于读取 get_global_rect() 的 Control。
new_accepted_types 可接收类型；为空表示不限制。
options 可选参数，支持 priority、enabled、metadata、can_accept、drop。

返回：新落点。

结构：

  • options: Dictionary，包含 priority: int、enabled: bool、metadata: Dictionary、can_accept: Callable 和 drop: Callable。