Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

GDScript exported properties

在 Godot 中，你可以导出类成员，其值会与其所附加的资源（例如场景）一起保存，也可以在属性编辑器中进行编辑。导出使用 @export 注解来实现。

@export var number: int = 5

在上面这个例子中，数值 5 会保存起来，并在属性编辑器中显示。

导出变量必须使用常量表达式来进行初始化，部分导出注解具有特殊类型，对变量类型不作要求（请参见下面的示例部分）。

导出成员变量的基本好处之一，便是让这些变量在编辑器中可见可改，这样一来，美术师和游戏设计师就可以修改这些会影响程序运行方式的值。为此，Godot 提供了一种特殊的导出语法。

备注

C# 等其他语言也可以导出属性。不同的语言有不同的属性导出语法，见 :ref:`doc_c_sharp_exports`来查看有关 C# 中的属性导出。

基本用法

如果为导出变量赋予了常量值或常量表达式值，则可以对该变量的值进行类型推断，并使该变量在编辑器中可用。

@export var number = 5

如果导出变量没有默认值，那么你可以为该变量添加类型限定。

@export var number: int

可以导出资源和节点。

@export var resource: Resource
@export var node: Node

导出项分组

可以将导出的属性用 @export_group <class_@GDScript_annotation_@export_group>`注解来进行分组管理。在该注解后声明的每个导出变量均会被囊括在该分组内。可以另起一个 ``@export_group("")` 注解来定义新的导出项分组。

@export_group("My Properties")
@export var number = 3

该注解的第二个参数只会囊括变量名以该参数开头的导出变量。

导出项分组无法嵌套定义，需要用 @export_subgroup 来在一个大的导出项分组里定义一个小分组。

@export_subgroup("Extra Properties")
@export var string = ""
@export var flag = false

也可以更改导出项的主分类，亦或通过 :ref:`@export_category <class_@GDScript_annotation_@export_category>`注解来在属性列表中新建导出项分类。

@export_category("Main Category")
@export var number = 3
@export var string = ""

@export_category("Extra Category")
@export var flag = false

备注

属性列表是根据类继承而组织起来的，但新建的导出项类别会破坏了这种结构，故使用时需要格外小心，创建公共项目时应格外谨慎使用之。

字符串用作文件路径

字符串可以用作文件的路径。

@export_file var f

字符串也可以用作文件目录路径。

@export_dir var f

字符串在用作是文件路径时，可以在提示项中提供自定义过滤器。

@export_file("*.txt") var f

也可以使用全局文件系统中的路径，仅支持工具模式脚本可以如此使用。

字符串还可以用作全局文件系统中某个 PNG 文件的路径。

@export_global_file("*.png") var tool_image

字符串也能用作全局文件系统中某个目录的路径。

@export_global_dir var tool_dir

多行文本注释会让编辑器使用大文本输入框来输入文本，而非那种小小的单行输入框。

@export_multiline var text

编辑器内限制值的输入范围

允许 0 到 20 之间的整数。

@export_range(0, 20) var i

允许 -10 到 20 之间的整数。

@export_range(-10, 20) var j

允许 -10 到 20 之间的数，调整步长为 0.2 。

@export_range(-10, 20, 0.2) var k: float

可以添加 "or_greater" 及/或 "or_less" 提示来突破编辑器滑条的范围限制。

@export_range(0, 100, 1, "or_greater", "or_less")

带缓动提示的浮点数

在编辑器里提供 'ease()' 函数的视觉呈现。

@export_exp_easing var transition_speed

颜色

使用红、绿、蓝、Alpha 值指定普通颜色。

@export var col: Color

使用红、绿、蓝值指定颜色（此时Alpha 始终为 1）。

@export_color_no_alpha var col: Color

节点

从 Godot 4.0 开始，脚本中可以直接将节点作为属性导出，不必再使用 NodePath：

# Allows any node.
@export var node: Node

# Allows any node that inherits from BaseButton.
# Custom classes declared with `class_name` can also be used.
@export var some_button: BaseButton

如果需要，仍可以像 Godot 3.x 中那样导出 NodePath：

@export var node_path: NodePath
var node = get_node(node_path)

如果想要限制 NodePath 的类型，可以使用 @export_node_path 注解：

@export_node_path("Button", "TouchScreenButton") var some_button

资源

@export var resource: Resource

在检查器里，可以将资源文件从文件系统面板中拖放到导出变量所对应的槽位中。

不过，打开检查器的下拉列表可能会导致要创建的资源类列表非常之长。因此，如果在导出资源时指定了 Resource 的子类，例如：

@export var resource: AnimationNode

那么下拉列表就会缩减限定到 AnimationNode 类资源及其子类资源上。

必须注意：即使在编辑器中未运行脚本，导出的属性仍可编辑。这一点可以与 使用工具模式的脚本 配合使用。

导出位标记

用作位标记的整数可以在一个属性中存储多个 true/ false （布尔）值。通过使用 @export_flags 注解来在编辑器中设置这些位标记：

# Set any of the given flags from the editor.
@export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0

你必须为每个位标记提供一个字符串描述。在本例中， Fire 的值是 1， Water 的值是 2， Earth 的值是 4， Wind 的值是 8。通常情况下应相应地定义常量（例如 const ELEMENT_WIND = 8 等）。

可以用逗号将每个位标记及其值分隔开来：:

@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0

只有 2 的 n 次幂的整数才能作为位标记值使用，其最小值为 1（即 2 的 0 次幂），0 即表示无任何位标记选中。你还可以添加其他位标记，并将这些位标记进行组合：:

@export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
var spell_targets = 0

也可以为项目设置中定义的物理层、渲染层和导航层提供导出提示：

@export_flags_2d_physics var layers_2d_physics
@export_flags_2d_render var layers_2d_render
@export_flags_2d_navigation var layers_2d_navigation
@export_flags_3d_physics var layers_3d_physics
@export_flags_3d_render var layers_3d_render
@export_flags_3d_navigation var layers_3d_navigation

使用位标记需要对位操作有一定的了解，若对此有疑问，请使用布尔变量代替位标记使用。

导出枚举

成员属性也可以通过将类型限定为一个枚举来导出，导出值为该枚举的枚举常量。编辑器会在相应位置创建一个列表，将枚举项按如“物体1”、“物体2”、“其他物体”的方式来进行排列显示。导出枚举的数值会按整数类型来存储。

enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
@export var x: NamedEnum

整数、字符串也可以与 @export_enum <class_@GDScript_annotation_@export_enum>`注解配合使用来将一个整型变量转变成一个数值列表。编辑器会在相应位置设置一个枚举列表，将诸如展示、法师、盗贼等职业逐一罗列出来。通过这种方式导出的枚举整数，其值对应于所选选项的索引（即 ``0`, 1 或 2 ）。

@export_enum("Warrior", "Magician", "Thief") var character_class: int

可以用逗号将每个位标记及其值分隔开来：:

@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int

如果变量类型是字符串，则枚举字符串本身就是该变量的可选数值。

@export_enum("Rebecca", "Mary", "Leah") var character_name: