:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/4.2/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/4.2/doc/classes/Object.xml. .. _class_Object: Object ====== **派生：** :ref:`AudioServer`, :ref:`CameraServer`, :ref:`ClassDB`, :ref:`DisplayServer`, :ref:`EditorFileSystemDirectory`, :ref:`EditorInterface`, :ref:`EditorPaths`, :ref:`EditorSelection`, :ref:`EditorUndoRedoManager`, :ref:`EditorVCSInterface`, :ref:`Engine`, :ref:`EngineDebugger`, :ref:`GDExtensionManager`, :ref:`Geometry2D`, :ref:`Geometry3D`, :ref:`GodotSharp`, :ref:`Input`, :ref:`InputMap`, :ref:`IP`, :ref:`JavaClassWrapper`, :ref:`JavaScriptBridge`, :ref:`JNISingleton`, :ref:`JSONRPC`, :ref:`MainLoop`, :ref:`Marshalls`, :ref:`MovieWriter`, :ref:`NavigationMeshGenerator`, :ref:`NavigationServer2D`, :ref:`NavigationServer3D`, :ref:`Node`, :ref:`OpenXRExtensionWrapperExtension`, :ref:`OpenXRInteractionProfileMetadata`, :ref:`OS`, :ref:`Performance`, :ref:`PhysicsDirectBodyState2D`, :ref:`PhysicsDirectBodyState3D`, :ref:`PhysicsDirectSpaceState2D`, :ref:`PhysicsDirectSpaceState3D`, :ref:`PhysicsServer2D`, :ref:`PhysicsServer2DManager`, :ref:`PhysicsServer3D`, :ref:`PhysicsServer3DManager`, :ref:`PhysicsServer3DRenderingServerHandler`, :ref:`ProjectSettings`, :ref:`RefCounted`, :ref:`RenderingDevice`, :ref:`RenderingServer`, :ref:`ResourceLoader`, :ref:`ResourceSaver`, :ref:`ResourceUID`, :ref:`ScriptLanguage`, :ref:`TextServerManager`, :ref:`ThemeDB`, :ref:`TileData`, :ref:`Time`, :ref:`TranslationServer`, :ref:`TreeItem`, :ref:`UndoRedo`, :ref:`WorkerThreadPool`, :ref:`XRServer` 引擎中所有其他类的基类。 .. rst-class:: classref-introduction-group 描述 ---- 一种高级的 :ref:`Variant` 类型。引擎中的所有类都继承自 Object。每个类都可以定义新的属性、方法或信号，并且这些对所有继承的类都可用。例如，一个 :ref:`Sprite2D` 实例能够调用 :ref:`Node.add_child` 因为它继承自 :ref:`Node`\ 。 可以使用 GDScript 中的 ``Object.new()`` 或 C# 中的 ``new GodotObject`` 来创建新实例。 要删除一个 Object 实例，请调用 :ref:`free`\ 。这对于大多数继承 Object 的类来说是必须的，因为它们本身并不管理内存，如果不调用该方法的话，在不再使用时会造成内存泄漏。有几个类会执行内存管理。例如，\ :ref:`RefCounted`\ （以及扩展的 :ref:`Resource`\ ）在不再被引用时删除自身，而 :ref:`Node` 在释放时会删除其子节点。 对象可以附加一个 :ref:`Script`\ 。一旦该 :ref:`Script` 被实例化，它就有效地充当了基类的扩展，允许它定义和继承新的属性、方法和信号。 在 :ref:`Script` 中，\ :ref:`_get_property_list` 可以被可以重写，以通过多种方式自定义属性。这允许它们对编辑器可用，显示为选项列表，细分为组，保存在磁盘上，等等。脚本语言提供更简单的方式来自定义属性，例如使用 :ref:`@GDScript.@export` 注解。 Godot 是非常动态的。一个对象的脚本，以及它的属性、方法和信号，都可以在运行时改变。正因为如此，可能会出现这样的情况，例如，一个方法所需的属性可能不存在。为了防止运行时出错，可以参考 :ref:`set`\ 、\ :ref:`get`\ 、\ :ref:`call`\ 、\ :ref:`has_method`\ 、\ :ref:`has_signal` 等方法。请注意，这些方法比直接引用慢\ **得多**\ 。 在 GDScript 中，还可以使用 ``in`` 运算符来检查对象中是否存在给定的属性、方法或信号名称： :: var node = Node.new() print("name" in node) # 输出 true print("get_parent" in node) # 输出 true print("tree_entered" in node) # 输出 true print("unknown" in node) # 输出 false 通知是 :ref:`int` 常量，通常由对象发送和接收。例如，在每个渲染帧上，\ :ref:`SceneTree` 使用 :ref:`Node.NOTIFICATION_PROCESS` 通知树内的节点。节点收到它后，可以调用 :ref:`Node._process` 进行更新。要使用通知，请参阅 :ref:`notification` 和 :ref:`_notification`\ 。 最后，每个对象还可以包含元数据（关于数据的数据）。\ :ref:`set_meta` 可用于存储对象本身不依赖的信息。为了保持代码整洁，不鼓励过度使用元数据。 \ **注意：**\ 与对 :ref:`RefCounted` 的引用不同，对存储在变量中的对象的引用，可能会在未被设置为 ``null`` 的情况下变得无效。要检查对象是否已被删除，请\ *不要*\ 将其与 ``null`` 进行比较。而是使用 :ref:`@GlobalScope.is_instance_valid`\ 。存储数据的类，建议从 :ref:`RefCounted` 继承而不是 **Object**\ 。 \ **注意：**\ ``script`` 不像大多数属性那样公开。要在代码中设置或获取一个对象的 :ref:`Script`\ ，请分别使用 :ref:`set_script` 和 :ref:`get_script`\ 。 .. rst-class:: classref-introduction-group 教程 ---- - :doc:`Object 类介绍 <../contributing/development/core_and_modules/object_class>` - :doc:`何时以及如何避免为任何事情使用节点 <../tutorials/best_practices/node_alternatives>` - :doc:`对象通知 <../tutorials/best_practices/godot_notifications>` .. rst-class:: classref-reftable-group 方法 ---- .. table:: :widths: auto +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`_get` **(** :ref:`StringName` property **)** |virtual| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary[]` | :ref:`_get_property_list` **(** **)** |virtual| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_init` **(** **)** |virtual| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_notification` **(** :ref:`int` what **)** |virtual| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`_property_can_revert` **(** :ref:`StringName` property **)** |virtual| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`_property_get_revert` **(** :ref:`StringName` property **)** |virtual| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`_set` **(** :ref:`StringName` property, :ref:`Variant` value **)** |virtual| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`_to_string` **(** **)** |virtual| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_validate_property` **(** :ref:`Dictionary` property **)** |virtual| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_user_signal` **(** :ref:`String` signal, :ref:`Array` arguments=[] **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`call` **(** :ref:`StringName` method, ... **)** |vararg| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`call_deferred` **(** :ref:`StringName` method, ... **)** |vararg| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`callv` **(** :ref:`StringName` method, :ref:`Array` arg_array **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`can_translate_messages` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`cancel_free` **(** **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`connect` **(** :ref:`StringName` signal, :ref:`Callable` callable, :ref:`int` flags=0 **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`disconnect` **(** :ref:`StringName` signal, :ref:`Callable` callable **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`emit_signal` **(** :ref:`StringName` signal, ... **)** |vararg| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`free` **(** **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get` **(** :ref:`StringName` property **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_class` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary[]` | :ref:`get_incoming_connections` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_indexed` **(** :ref:`NodePath` property_path **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_instance_id` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_meta` **(** :ref:`StringName` name, :ref:`Variant` default=null **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`StringName[]` | :ref:`get_meta_list` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary[]` | :ref:`get_method_list` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary[]` | :ref:`get_property_list` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_script` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary[]` | :ref:`get_signal_connection_list` **(** :ref:`StringName` signal **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary[]` | :ref:`get_signal_list` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_meta` **(** :ref:`StringName` name **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_method` **(** :ref:`StringName` method **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_signal` **(** :ref:`StringName` signal **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_user_signal` **(** :ref:`StringName` signal **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_blocking_signals` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_class` **(** :ref:`String` class **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_connected` **(** :ref:`StringName` signal, :ref:`Callable` callable **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_queued_for_deletion` **(** **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`notification` **(** :ref:`int` what, :ref:`bool` reversed=false **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`notify_property_list_changed` **(** **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`property_can_revert` **(** :ref:`StringName` property **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`property_get_revert` **(** :ref:`StringName` property **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_meta` **(** :ref:`StringName` name **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set` **(** :ref:`StringName` property, :ref:`Variant` value **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_block_signals` **(** :ref:`bool` enable **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_deferred` **(** :ref:`StringName` property, :ref:`Variant` value **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_indexed` **(** :ref:`NodePath` property_path, :ref:`Variant` value **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_message_translation` **(** :ref:`bool` enable **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_meta` **(** :ref:`StringName` name, :ref:`Variant` value **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_script` **(** :ref:`Variant` script **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`to_string` **(** **)** | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`tr` **(** :ref:`StringName` message, :ref:`StringName` context="" **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`tr_n` **(** :ref:`StringName` message, :ref:`StringName` plural_message, :ref:`int` n, :ref:`StringName` context="" **)** |const| | +---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 信号 ---- .. _class_Object_signal_property_list_changed: .. rst-class:: classref-signal **property_list_changed** **(** **)** 调用 :ref:`notify_property_list_changed` 时发出。 .. rst-class:: classref-item-separator ---- .. _class_Object_signal_script_changed: .. rst-class:: classref-signal **script_changed** **(** **)** 该对象的脚本发生改变时发出。 \ **注意：**\ 发出这个信号时，新脚本还没有初始化。如果你需要访问新脚本，请用 :ref:`CONNECT_DEFERRED` 推迟与这个信号的连接。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 枚举 ---- .. _enum_Object_ConnectFlags: .. rst-class:: classref-enumeration enum **ConnectFlags**: .. _class_Object_constant_CONNECT_DEFERRED: .. rst-class:: classref-enumeration-constant :ref:`ConnectFlags` **CONNECT_DEFERRED** = ``1`` 延迟连接会在空闲时触发 :ref:`Callable`\ （当前帧的末尾），不会立即触发。 .. _class_Object_constant_CONNECT_PERSIST: .. rst-class:: classref-enumeration-constant :ref:`ConnectFlags` **CONNECT_PERSIST** = ``2`` 持久连接会在序列化对象时存储（比如使用 :ref:`PackedScene.pack` 时）。在编辑器中，通过“节点”面板创建的连接总是持久的。 .. _class_Object_constant_CONNECT_ONE_SHOT: .. rst-class:: classref-enumeration-constant :ref:`ConnectFlags` **CONNECT_ONE_SHOT** = ``4`` 一次性连接，会在触发后自行断开。 .. _class_Object_constant_CONNECT_REFERENCE_COUNTED: .. rst-class:: classref-enumeration-constant :ref:`ConnectFlags` **CONNECT_REFERENCE_COUNTED** = ``8`` 引用计数连接可以多次分配给同一个 :ref:`Callable`\ 。每断开一次连接会让内部计数器减一。信号会在计数器变为 0 时完全断开连接。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 常量 ---- .. _class_Object_constant_NOTIFICATION_POSTINITIALIZE: .. rst-class:: classref-constant **NOTIFICATION_POSTINITIALIZE** = ``0`` 该对象初始化时收到的通知，发生在附加脚本之前。内部使用。 .. _class_Object_constant_NOTIFICATION_PREDELETE: .. rst-class:: classref-constant **NOTIFICATION_PREDELETE** = ``1`` 该对象即将被删除时收到的通知。可以当作其他编程语言中的析构函数。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 方法说明 -------- .. _class_Object_private_method__get: .. rst-class:: classref-method :ref:`Variant` **_get** **(** :ref:`StringName` property **)** |virtual| 覆盖该方法以自定义 :ref:`get` 的行为。应该返回给定的 ``property`` 的值，或者 ``property`` 应该被正常处理时返回 ``null``\ 。 结合 :ref:`_set` 和 :ref:`_get_property_list`\ ，该方法允许定义自定义属性，这对编辑器插件特别有用。请注意，属性必须存在于 :ref:`get_property_list` 中，否则该方法不会被调用。 .. tabs:: .. code-tab:: gdscript func _get(property): if property == "fake_property": print("正在获取我的属性！") return 4 func _get_property_list(): return [ { "name": "fake_property", "type": TYPE_INT } ] .. code-tab:: csharp public override Variant _Get(StringName property) { if (property == "FakeProperty") { GD.Print("正在获取我的属性！"); return 4; } return default; } public override Godot.Collections.Array _GetPropertyList() { return new Godot.Collections.Array() { new Godot.Collections.Dictionary() { { "name", "FakeProperty" }, { "type", (int)Variant.Type.Int } } }; } .. rst-class:: classref-item-separator ---- .. _class_Object_private_method__get_property_list: .. rst-class:: classref-method :ref:`Dictionary[]` **_get_property_list** **(** **)** |virtual| 覆盖该方法以自定义引擎处理脚本属性的方式。 应该返回一个属性列表，作为字典的 :ref:`Array`\ 。该结果被添加到 :ref:`get_property_list` 的数组中，并且应该以相同的方式进行格式化。每个 :ref:`Dictionary` 必须至少包含 ``name`` 和 ``type`` 条目。 以下示例仅在 ``holding_hammer`` 为 ``true`` 时，在检查器停靠面板中显示 ``hammer_type``\ ： .. tabs:: .. code-tab:: gdscript @tool extends Node2D @export var holding_hammer = false: set(value): holding_hammer = value notify_property_list_changed() var hammer_type = 0 func _get_property_list(): # 默认情况下，`hammer_type` 在编辑器中不可见。 var property_usage = PROPERTY_USAGE_NO_EDITOR if holding_hammer: property_usage = PROPERTY_USAGE_DEFAULT var properties = [] properties.append({ "name": "hammer_type", "type": TYPE_INT, "usage": property_usage, # 参见上面的赋值。 "hint": PROPERTY_HINT_ENUM, "hint_string": "Wooden,Iron,Golden,Enchanted" }) return properties .. code-tab:: csharp [Tool] public partial class MyNode2D : Node2D { private bool _holdingHammer; [Export] public bool HoldingHammer { get => _holdingHammer; set { _holdingHammer = value; NotifyPropertyListChanged(); } } public int HammerType { get; set; } public override Godot.Collections.Array _GetPropertyList() { // 默认情况下，`HammerType` 在编辑器中不可见。 var propertyUsage = PropertyUsageFlags.NoEditor; if (HoldingHammer) { propertyUsage = PropertyUsageFlags.Default; } var properties = new Godot.Collections.Array(); properties.Add(new Godot.Collections.Dictionary() { { "name", "HammerType" }, { "type", (int)Variant.Type.Int }, { "usage", (int)propertyUsage }, // 参见上面的赋值。 { "hint", (int)PropertyHint.Enum }, { "hint_string", "Wooden,Iron,Golden,Enchanted" } }); return properties; } } \ **注意：**\ 该方法旨在用于高级目的。对于大多数常见用例，脚本语言提供了更简单的方法来处理属性。参见 :ref:`@GDScript.@export`\ 、\ :ref:`@GDScript.@export_enum`\ 、\ :ref:`@GDScript.@export_group`\ 、等。 \ **注意：**\ 如果该对象的脚本不是 :ref:`@GDScript.@tool`\ ，则该方法在编辑器中不会被调用。 .. rst-class:: classref-item-separator ---- .. _class_Object_private_method__init: .. rst-class:: classref-method void **_init** **(** **)** |virtual| 实例化对象的脚本时调用，通常是在对象在内存中初始化之后（通过 GDScript 中的 ``Object.new()`` 或 C# 中的 ``new GodotObject``\ ）。也可以将其定义为接受参数的形式。该方法类似于大多数编程语言中的构造函数。 \ **注意：**\ 如果为 :ref:`_init` 定义了\ *必填的*\ 参数，则带脚本的 Object 只能直接创建。使用任何其他方式（例如 :ref:`PackedScene.instantiate` 或 :ref:`Node.duplicate`\ ）创建时，该脚本的初始化都将失败。 .. rst-class:: classref-item-separator ---- .. _class_Object_private_method__notification: .. rst-class:: classref-method void **_notification** **(** :ref:`int` what **)** |virtual| 当对象收到通知时被调用，可以通过将 ``what`` 与常量比较来识别通知。另见 :ref:`notification`\ 。 .. tabs:: .. code-tab:: gdscript func _notification(what): if what == NOTIFICATION_PREDELETE: print("再见！") .. code-tab:: csharp public override void _Notification(int what) { if (what == NotificationPredelete) { GD.Print("再见！"); } } \ **注意：**\ 基类 **Object** 定义了一些通知（\ :ref:`NOTIFICATION_POSTINITIALIZE` 和 :ref:`NOTIFICATION_PREDELETE`\ ）。\ :ref:`Node` 等继承类定义了更多通知，这些通知也由该方法接收。 .. rst-class:: classref-item-separator ---- .. _class_Object_private_method__property_can_revert: .. rst-class:: classref-method :ref:`bool` **_property_can_revert** **(** :ref:`StringName` property **)** |virtual| 覆盖该方法以自定义给定 ``property`` 的还原行为。如果 ``property`` 可以在检查器停靠面板中恢复，则应该返回 ``true``\ 。使用 :ref:`_property_get_revert` 来指定 ``property`` 的默认值。 \ **注意：**\ 无论 ``property`` 的当前值如何，该方法都必须始终如一地返回。 .. rst-class:: classref-item-separator ---- .. _class_Object_private_method__property_get_revert: .. rst-class:: classref-method :ref:`Variant` **_property_get_revert** **(** :ref:`StringName` property **)** |virtual| 覆盖该方法以自定义给定 ``property`` 的还原行为。应返回 ``property`` 的默认值。如果默认值与 ``property`` 的当前值不同，则检查器停靠面板中会显示一个还原图标。 \ **注意：**\ :ref:`_property_can_revert` 也必须被覆盖，该方法才能被调用。 .. rst-class:: classref-item-separator ---- .. _class_Object_private_method__set: .. rst-class:: classref-method :ref:`bool` **_set** **(** :ref:`StringName` property, :ref:`Variant` value **)** |virtual| 覆盖该方法以自定义 :ref:`set` 的行为。应将 ``property`` 设置为 ``value`` 并返回 ``true``\ ，如果 ``property`` 正常处理则返回 ``false``\ 。设置 ``property`` 的\ *确切*\ 方式取决于该方法的实现。 结合 :ref:`_get` 和 :ref:`_get_property_list`\ ，该方法允许定义自定义属性，这对编辑器插件特别有用。注意属性\ *必须*\ 在 :ref:`get_property_list` 中存在，否则该方法将不会被调用。 .. tabs:: .. code-tab:: gdscript var internal_data = {} func _set(property, value): if property == "fake_property": # 在冒牌属性中存值。 internal_data["fake_property"] = value return true return false func _get_property_list(): return [ { "name": "fake_property", "type": TYPE_INT } ] .. code-tab:: csharp private Godot.Collections.Dictionary _internalData = new Godot.Collections.Dictionary(); public override bool _Set(StringName property, Variant value) { if (property == "FakeProperty") { // 在冒牌属性中存值。 _internalData["FakeProperty"] = value; return true; } return false; } public override Godot.Collections.Array _GetPropertyList() { return new Godot.Collections.Array() { new Godot.Collections.Dictionary() { { "name", "FakeProperty" }, { "type", (int)Variant.Type.Int } } }; } .. rst-class:: classref-item-separator ---- .. _class_Object_private_method__to_string: .. rst-class:: classref-method :ref:`String` **_to_string** **(** **)** |virtual| 覆盖该方法以自定义 :ref:`to_string` 的返回值，从而将对象表示为一个 :ref:`String`\ 。 :: func _to_string(): return "欢迎来到 Godot 4！" func _init(): print(self) # 输出“欢迎来到 Godot 4！” var a = str(self) # a 是“欢迎来到 Godot 4！” .. rst-class:: classref-item-separator ---- .. _class_Object_private_method__validate_property: .. rst-class:: classref-method void **_validate_property** **(** :ref:`Dictionary` property **)** |virtual| 覆盖该方法以自定义已有属性。每个属性信息都经过该方法。字典内容与 :ref:`_get_property_list` 中的相同。 .. tabs:: .. code-tab:: gdscript @tool extends Node @export var is_number_editable: bool: set(value): is_number_editable = value notify_property_list_changed() @export var number: int func _validate_property(property: Dictionary): if property.name == "number" and not is_number_editable: property.usage |= PROPERTY_USAGE_READ_ONLY .. code-tab:: csharp [Tool] public partial class MyNode : Node { private bool _isNumberEditable; [Export] public bool IsNumberEditable { get => _isNumberEditable; set { _isNumberEditable = value; NotifyPropertyListChanged(); } } [Export] public int Number { get; set; } public override void _ValidateProperty(Godot.Collections.Dictionary property) { if (property["name"].AsStringName() == PropertyName.Number && IsNumberEditable) { var usage = property["usage"].As>PropertyUsageFlags<() | PropertyUsageFlags.ReadOnly; property["usage"] = (int)usage; } } } .. rst-class:: classref-item-separator ---- .. _class_Object_method_add_user_signal: .. rst-class:: classref-method void **add_user_signal** **(** :ref:`String` signal, :ref:`Array` arguments=[] **)** 添加用户定义的信号 ``signal``\ 。信号的参数是可选的，以字典的 :ref:`Array` 形式添加，字典中定义名称 ``name`` :ref:`String`\ ，类型 ``type`` :ref:`int`\ （见 :ref:`Variant.Type`\ ）。另见 :ref:`has_user_signal`\ 。 .. tabs:: .. code-tab:: gdscript add_user_signal("hurt", [ { "name": "damage", "type": TYPE_INT }, { "name": "source", "type": TYPE_OBJECT } ]) .. code-tab:: csharp AddUserSignal("Hurt", new Godot.Collections.Array() { new Godot.Collections.Dictionary() { { "name", "damage" }, { "type", (int)Variant.Type.Int } }, new Godot.Collections.Dictionary() { { "name", "source" }, { "type", (int)Variant.Type.Object } } }); .. rst-class:: classref-item-separator ---- .. _class_Object_method_call: .. rst-class:: classref-method :ref:`Variant` **call** **(** :ref:`StringName` method, ... **)** |vararg| 在对象上调用 ``method`` 并返回结果。该方法支持可变数量的参数，因此参数可以作为逗号分隔的列表传递。 .. tabs:: .. code-tab:: gdscript var node = Node3D.new() node.call("rotate", Vector3(1.0, 0.0, 0.0), 1.571) .. code-tab:: csharp var node = new Node3D(); node.Call(Node3D.MethodName.Rotate, new Vector3(1f, 0f, 0f), 1.571f); \ **注意：**\ 在 C# 中，在引用 Godot 内置方法时，\ ``method`` 必须为 snake_case 格式。最好使用 ``MethodName`` 类中公开的名称，以避免在每次调用时分配新的 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_call_deferred: .. rst-class:: classref-method :ref:`Variant` **call_deferred** **(** :ref:`StringName` method, ... **)** |vararg| 在空闲时调用该对象的 ``method`` 方法。始终返回 null，\ **不返回**\ 该方法的结果。 空闲时间主要出现在处理帧和物理帧的末尾。此时会执行延迟调用，直到全部调用完毕，也就是说延迟调用中也可以进行延迟调用，这种情况下就仍然是在当前空闲时间周期中执行。如果没有谨慎处理，可能导致无限递归，但不会导致栈溢出，后者会像死循环一样让游戏死机。 这个方法支持可变数量的参数，所以参数可以用逗号分隔列表的形式传递。 .. tabs:: .. code-tab:: gdscript var node = Node3D.new() node.call_deferred("rotate", Vector3(1.0, 0.0, 0.0), 1.571) .. code-tab:: csharp var node = new Node3D(); node.CallDeferred(Node3D.MethodName.Rotate, new Vector3(1f, 0f, 0f), 1.571f); 另见 :ref:`Callable.call_deferred`\ 。 \ **注意：**\ 在 C# 中，\ ``method`` 引用内置的 Godot 方法时必须使用 snake_case 的形式。请优先使用 ``MethodName`` 类中暴露的名称，避免每次调用都分配一个新的 :ref:`StringName`\ 。 \ **注意：**\ 如果你想要延迟一帧再调用函数，请使用 :ref:`SceneTree.process_frame` 和 :ref:`SceneTree.physics_frame` 信号。 :: var node = Node3D.new() # 制作可调用体并将参数绑定到该节点的 rotate() 调用。 var callable = node.rotate.bind(Vector3(1.0, 0.0, 0.0), 1.571) # 将可调用体连接到 process_frame 信号，这样就能够在下一个处理帧中调用。 # CONNECT_ONE_SHOT 能够确保只调用一次，不会每帧都调用。 get_tree().process_frame.connect(callable, CONNECT_ONE_SHOT) .. rst-class:: classref-item-separator ---- .. _class_Object_method_callv: .. rst-class:: classref-method :ref:`Variant` **callv** **(** :ref:`StringName` method, :ref:`Array` arg_array **)** 在对象上调用 ``method`` 并返回结果。与 :ref:`call` 不同，该方法期望所有参数都包含在 ``arg_array`` 中。 .. tabs:: .. code-tab:: gdscript var node = Node3D.new() node.callv("rotate", [Vector3(1.0, 0.0, 0.0), 1.571]) .. code-tab:: csharp var node = new Node3D(); node.Callv(Node3D.MethodName.Rotate, new Godot.Collections.Array { new Vector3(1f, 0f, 0f), 1.571f }); \ **注意：**\ 在 C# 中，\ ``method`` 在引用 Godot 内置方法时必须是 snake_case。最好使用 ``MethodName`` 类中公开的名称，以避免在每次调用时分配新的 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_can_translate_messages: .. rst-class:: classref-method :ref:`bool` **can_translate_messages** **(** **)** |const| 如果允许该对象使用 :ref:`tr` 和 :ref:`tr_n` 翻译消息，则返回 ``true``\ 。另见 :ref:`set_message_translation`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_cancel_free: .. rst-class:: classref-method void **cancel_free** **(** **)** 如果在 :ref:`NOTIFICATION_PREDELETE` 时调用该方法，则该对象拒绝释放，仍会保持已分配的状态。主要是作为内部函数使用，用于错误处理，避免用户释放不想释放的对象。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_connect: .. rst-class:: classref-method :ref:`Error` **connect** **(** :ref:`StringName` signal, :ref:`Callable` callable, :ref:`int` flags=0 **)** 按名称将 ``signal`` 连接到 ``callable``\ 。还可以添加可选的 ``flags`` 来配置该连接的行为（请参阅 :ref:`ConnectFlags` 常量）。 一个信号只能连接到同一个 :ref:`Callable` 一次。如果该信号已经连接，除非该信号是使用 :ref:`CONNECT_REFERENCE_COUNTED` 连接的，否则该方法会返回 :ref:`@GlobalScope.ERR_INVALID_PARAMETER` 并推送一条错误消息。为防止这种情况，请首先使用 :ref:`is_connected` 检查已存在的连接。 如果 ``callable`` 的对象被释放，则该连接将会丢失。 \ **推荐语法的示例：**\ 连接信号是 Godot 中最常见的操作之一，API 提供了许多这样做的选项，这些选项将在下面进一步介绍。下面的代码块显示了推荐的方法。 .. tabs:: .. code-tab:: gdscript func _ready(): var button = Button.new() # 这里的 `button_down` 是一个 Signal 变体类型，因此我们调用 Signal.connect() 方法，而不是 Object.connect()。 # 请参阅下面的讨论以更深入地了解该 API。 button.button_down.connect(_on_button_down) # 这假设存在一个“Player”类，它定义了一个“hit”信号。 var player = Player.new() # 我们再次使用 Signal.connect() ，并且我们还使用了 Callable.bind() 方法， # 它返回一个带有参数绑定的新 Callable。 player.hit.connect(_on_player_hit.bind("剑", 100)) func _on_button_down(): print("按钮按下！") func _on_player_hit(weapon_type, damage): print("用武器 %s 击中，造成 %d 伤害。" % [weapon_type, damage]) .. code-tab:: csharp public override void _Ready() { var button = new Button(); // C# 支持将信号作为事件传递，因此我们可以使用这个惯用的构造： button.ButtonDown += OnButtonDown; // 这假设存在一个“Player”类，它定义了一个“Hit”信号。 var player = new Player(); // 当我们需要绑定额外的参数时，我们可以使用 Lambda 表达式。 player.Hit += () => OnPlayerHit("剑", 100); } private void OnButtonDown() { GD.Print("按钮按下！"); } private void OnPlayerHit(string weaponType, int damage) { GD.Print($"用武器 {weaponType} 击中，造成 {damage} 伤害。"); } \ **\ ``Object.connect()`` 还是 ``Signal.connect()``\ ？**\ 如上所示，推荐的连接信号的方法不是 :ref:`connect`\ 。下面的代码块显示了连接信号的四个选项，使用该传统方法或推荐的 :ref:`Signal.connect`\ ，并使用一个隐式的 :ref:`Callable` 或手动定义的 :ref:`Callable`\ 。 .. tabs:: .. code-tab:: gdscript func _ready(): var button = Button.new() # 选项 1：Object.connect() 并使用已定义的函数的隐式 Callable。 button.connect("button_down", _on_button_down) # 选项 2：Object.connect() 并使用由目标对象和方法名称构造的 Callable。 button.connect("button_down", Callable(self, "_on_button_down")) # 选项 3：Signal.connect() 并使用已定义的函数的隐式 Callable。 button.button_down.connect(_on_button_down) # 选项 4：Signal.connect() 并使用由目标对象和方法名称构造的 Callable。 button.button_down.connect(Callable(self, "_on_button_down")) func _on_button_down(): print("按钮按下！") .. code-tab:: csharp public override void _Ready() { var button = new Button(); // 选项 1：在 C# 中，我们可以将信号用作事件并使用以下惯用语法进行连接： button.ButtonDown += OnButtonDown; // 选项 2：GodotObject.Connect() 并使用从方法组构造的 Callable。 button.Connect(Button.SignalName.ButtonDown, Callable.From(OnButtonDown)); // 选项 3：GodotObject.Connect() 并使用由目标对象和方法名称构造的 Callable。 button.Connect(Button.SignalName.ButtonDown, new Callable(this, MethodName.OnButtonDown)); } private void OnButtonDown() { GD.Print("按钮按下！"); } 虽然所有选项都有相同的结果（\ ``button`` 的 :ref:`BaseButton.button_down` 信号将被连接到 ``_on_button_down``\ ），但\ **选项 3** 提供了最好的验证：如果 ``button_down`` :ref:`Signal` 或 ``_on_button_down`` :ref:`Callable` 没有被定义，它将打印一个编译时错误。另一方面，\ **选项 2** 只依赖于字符串名称，并且只能在运行时验证这两个名称：如果 ``"button_down"`` 不对应于一个信号，或者如果 ``"_on_button_down"`` 不是对象 ``self`` 中的注册方法，它将打印一个运行时错误。使用选项 1、2 或 4 的主要原因，是你是否确实需要使用字符串（例如，根据从配置文件读取的字符串，以编程的方式连接信号）。否则，选项 3 是推荐的（也是最快的）方法。 \ **绑定和传递参数：**\ 绑定参数的语法是通过 :ref:`Callable.bind`\ ，它返回一个绑定了参数的 :ref:`Callable` 的副本。 当调用 :ref:`emit_signal` 时，信号参数也可以被传递。下面的示例显示了这些信号参数和绑定参数之间的关系。 .. tabs:: .. code-tab:: gdscript func _ready(): # 这假设存在一个 `Player` 类，它定义了一个 `hit` 信号。 var player = Player.new() # 使用 Callable.bind()。 player.hit.connect(_on_player_hit.bind("剑", 100)) # 发出信号时添加的参数首先被传递。 player.emit_signal("hit", "黑暗领主", 5) # 我们在发出时传递两个参数（`hit_by`，`level`）， # 并在连接时再绑定两个参数（`weapon_type`、`damage`）。 func _on_player_hit(hit_by, level, weapon_type, damage): print("被 %s（等级 %d）用武器 %s 击中，造成 %d 伤害。" % [hit_by, level, weapon_type, damage]) .. code-tab:: csharp public override void _Ready() { // 这假设存在一个 `Player` 类，它定义了一个 `Hit` 信号。 var player = new Player(); // 使用 lambda 表达式创建一个闭包来捕获额外的参数。 // lambda 仅接收由信号委托定义的参数。 player.Hit += (hitBy, level) => OnPlayerHit(hitBy, level, "剑", 100); // 发出信号时添加的参数首先被传递。 player.EmitSignal(SignalName.Hit, "黑暗领主", 5); } // 我们在发出时传递两个参数（`hit_by`，`level`）， // 并在连接时再绑定两个参数（`weapon_type`、`damage`）。 private void OnPlayerHit(string hitBy, int level, string weaponType, int damage) { GD.Print($"被 {hitBy}（等级 {level}）用武器 {weaponType} 击中，造成 {damage} 伤害。"); } .. rst-class:: classref-item-separator ---- .. _class_Object_method_disconnect: .. rst-class:: classref-method void **disconnect** **(** :ref:`StringName` signal, :ref:`Callable` callable **)** 按名称从给定的 ``callable`` 断开 ``signal``\ 。如果连接不存在，则生成一个错误。使用 :ref:`is_connected` 确保该连接存在。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_emit_signal: .. rst-class:: classref-method :ref:`Error` **emit_signal** **(** :ref:`StringName` signal, ... **)** |vararg| 按名称发出给定的 ``signal``\ 。该信号必须存在，所以它应该是该类或其继承类之一的内置信号，或者是用户定义的信号（参见 :ref:`add_user_signal`\ ）。该方法支持可变数量的参数，所以参数可以以逗号分隔的列表形式传递。 如果 ``signal`` 不存在或参数无效，则返回 :ref:`@GlobalScope.ERR_UNAVAILABLE`\ 。 .. tabs:: .. code-tab:: gdscript emit_signal("hit", "剑", 100) emit_signal("game_over") .. code-tab:: csharp EmitSignal(SignalName.Hit, "剑", 100); EmitSignal(SignalName.GameOver); \ **注意：**\ 在C#中，在引用内置 Godot 信号时，\ ``signal`` 必须是 snake_case。最好使用 ``SignalName`` 类中公开的名称，以避免在每次调用时分配一个新的 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_free: .. rst-class:: classref-method void **free** **(** **)** 从内存中删除该对象。对该对象的预先存在的引用会变得无效，并且任何访问它们的尝试都将会产生一个运行时错误。使用 :ref:`@GlobalScope.is_instance_valid` 检查引用时将返回 ``false``\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get: .. rst-class:: classref-method :ref:`Variant` **get** **(** :ref:`StringName` property **)** |const| 返回给定 ``property`` 的 :ref:`Variant` 值。如果 ``property`` 不存在，则该方法返回 ``null``\ 。 .. tabs:: .. code-tab:: gdscript var node = Node2D.new() node.rotation = 1.5 var a = node.get("rotation") # a 为 1.5 .. code-tab:: csharp var node = new Node2D(); node.Rotation = 1.5f; var a = node.Get("rotation"); // a 为 1.5 \ **注意：**\ 在 C# 中，在引用 Godot 内置属性时，\ ``property`` 必须是 snake_case。最好使用 ``PropertyName`` 类中公开的名称，以避免在每次调用时分配一个新的 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_class: .. rst-class:: classref-method :ref:`String` **get_class** **(** **)** |const| 返回该对象的内置类名，作为一个 :ref:`String`\ 。另请参阅 :ref:`is_class`\ 。 \ **注意：**\ 该方法将忽略 ``class_name`` 声明。如果该对象的脚本定义了一个 ``class_name``\ ，则改为返回内置基类名称。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_incoming_connections: .. rst-class:: classref-method :ref:`Dictionary[]` **get_incoming_connections** **(** **)** |const| 返回该对象接收到的信号连接的 :ref:`Array`\ 。每个连接都被表示为包含三个条目的 :ref:`Dictionary`\ ： - ``signal`` 是对 :ref:`Signal` 的引用； - ``callable`` 是对 :ref:`Callable` 的引用； - ``flags`` 是 :ref:`ConnectFlags` 的组合。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_indexed: .. rst-class:: classref-method :ref:`Variant` **get_indexed** **(** :ref:`NodePath` property_path **)** |const| 获取该对象的某个属性，该属性的属性路径由 ``property_path`` 给出。该路径应该是相对于当前对象的 :ref:`NodePath`\ ，可是使用英文冒号（\ ``:``\ ）访问内嵌属性。 \ **示例：**\ ``"position:x"`` 或 ``"material:next_pass:blend_mode"``\ 。 .. tabs:: .. code-tab:: gdscript var node = Node2D.new() node.position = Vector2(5, -10) var a = node.get_indexed("position") # a 为 Vector2(5, -10) var b = node.get_indexed("position:y") # b 为 -10 .. code-tab:: csharp var node = new Node2D(); node.Position = new Vector2(5, -10); var a = node.GetIndexed("position"); // a 为 Vector2(5, -10) var b = node.GetIndexed("position:y"); // b 为 -10 \ **注意：**\ 在 C# 中引用内置 Godot 属性时 ``property_path`` 必须为 snake_case 蛇形大小写。请优先使用 ``PropertyName`` 类中暴露的名称，避免每次调用都重新分配一个 :ref:`StringName`\ 。 \ **注意：**\ 这个方法不支持指向 :ref:`SceneTree` 中节点的路径，仅支持子属性路径。在节点语境下，请改用 :ref:`Node.get_node_and_resource`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_instance_id: .. rst-class:: classref-method :ref:`int` **get_instance_id** **(** **)** |const| 返回该对象的唯一实例 ID。该 ID 可以保存在 :ref:`EncodedObjectAsID` 中，并可用于 :ref:`@GlobalScope.instance_from_id`\ ，来检索该对象实例。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_meta: .. rst-class:: classref-method :ref:`Variant` **get_meta** **(** :ref:`StringName` name, :ref:`Variant` default=null **)** |const| 返回该对象的元数据中名称为 ``name`` 的条目。如果不存在该条目，则返回 ``default``\ 。如果 ``default`` 为 ``null``\ ，则还会生成错误。 \ **注意：**\ 元数据的名称必须是符合 :ref:`StringName.is_valid_identifier` 的有效标识符。 \ **注意：**\ 名称以下划线（\ ``_``\ ）开头的元数据仅供编辑器使用。仅供编辑器使用的元数据不会在“检查器”中显示，虽然仍然能够被这个方法找到，但是不应该进行编辑。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_meta_list: .. rst-class:: classref-method :ref:`StringName[]` **get_meta_list** **(** **)** |const| 将该对象的元数据作为 :ref:`PackedStringArray` 返回。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_method_list: .. rst-class:: classref-method :ref:`Dictionary[]` **get_method_list** **(** **)** |const| 将该对象的方法及对应签名作为字典 :ref:`Array` 返回。每个 :ref:`Dictionary` 包含以下条目： -``name`` 是该方法的名称，为 :ref:`String`\ ； -``args`` 是代表参数的字典 :ref:`Array`\ ； -``default_args`` 是默认参数，为变体 :ref:`Array`\ ； -``flags`` 是 :ref:`MethodFlags` 的组合； -``id`` 是该方法的内部标识符 :ref:`int`\ ； -``return`` 是返回值，为 :ref:`Dictionary`\ ； \ **注意：**\ ``args`` 和 ``return`` 的字典格式与 :ref:`get_property_list` 的结果相同，但不会用到所有条目。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_property_list: .. rst-class:: classref-method :ref:`Dictionary[]` **get_property_list** **(** **)** |const| 以字典 :ref:`Array` 的形式返回该对象的属性列表。每个 :ref:`Dictionary` 中都包含如下条目： - ``name`` 是该属性的名称，类型为 :ref:`String`\ ； - ``class_name`` 为空 :ref:`StringName`\ ，除非该属性为 :ref:`@GlobalScope.TYPE_OBJECT` 并继承自某个类； - ``type`` 是该属性的类型，类型为 :ref:`int`\ （见 :ref:`Variant.Type`\ ）； - ``hint`` 是应当\ *如何*\ 编辑该属性（见 :ref:`PropertyHint`\ ）； - ``hint_string`` 取决于 hint（见 :ref:`PropertyHint`\ ）； - ``usage`` 是 :ref:`PropertyUsageFlags` 的组合。 \ **注意：**\ 在 GDScript 中，类的所有成员都被视为属性。在 C# 和 GDExtension 中，则需要使用装饰器或特性将类的成员显式标记为 Godot 属性。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_script: .. rst-class:: classref-method :ref:`Variant` **get_script** **(** **)** |const| 返回该对象的 :ref:`Script` 实例，如果没有附加脚本，则返回 ``null``\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_signal_connection_list: .. rst-class:: classref-method :ref:`Dictionary[]` **get_signal_connection_list** **(** :ref:`StringName` signal **)** |const| 返回给定 ``signal`` 名称的连接的 :ref:`Array`\ 。每个连接都被表示为包含三个条目的 :ref:`Dictionary`\ ： - ``signal`` 是对 :ref:`Signal` 的引用； - ``callable`` 是对已连接 :ref:`Callable` 的引用； - ``flags`` 是 :ref:`ConnectFlags` 的组合。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_get_signal_list: .. rst-class:: classref-method :ref:`Dictionary[]` **get_signal_list** **(** **)** |const| 将现有信号的列表返回为字典的一个 :ref:`Array` 。 \ **注意：**\ 由于该实现，每个 :ref:`Dictionary` 被格式为与 :ref:`get_method_list` 的返回值非常相似。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_has_meta: .. rst-class:: classref-method :ref:`bool` **has_meta** **(** :ref:`StringName` name **)** |const| 如果找到名称为 ``name`` 的元数据条目，则返回 ``true``\ 。另请参阅 :ref:`get_meta`\ 、\ :ref:`set_meta` 和 :ref:`remove_meta`\ 。 \ **注意：**\ 元数据的名称必须是符合 :ref:`StringName.is_valid_identifier` 的有效标识符。 \ **注意：**\ 名称以下划线（\ ``_``\ ）开头的元数据仅供编辑器使用。仅供编辑器使用的元数据不会在“检查器”中显示，虽然仍然能够被这个方法找到，但是不应该进行编辑。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_has_method: .. rst-class:: classref-method :ref:`bool` **has_method** **(** :ref:`StringName` method **)** |const| 如果该对象中存在给定的方法名 ``method``\ ，则返回 ``true``\ 。 \ **注意：**\ 在 C# 中引用内置 Godot 方法时 ``method`` 必须为 snake_case 蛇形大小写。请优先使用 ``MethodName`` 类中暴露的名称，避免每次调用都重新分配一个 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_has_signal: .. rst-class:: classref-method :ref:`bool` **has_signal** **(** :ref:`StringName` signal **)** |const| 如果该对象中存在给定的信号名 ``signal``\ ，则返回 ``true``\ 。 \ **注意：**\ 在 C# 中引用内置 Godot 信号时 ``signal`` 必须为 snake_case 蛇形大小写。请优先使用 ``SignalName`` 类中暴露的名称，避免每次调用都重新分配一个 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_has_user_signal: .. rst-class:: classref-method :ref:`bool` **has_user_signal** **(** :ref:`StringName` signal **)** |const| 如果存在给定的用户定义信号名称 ``signal``\ ，则返回 ``true``\ 。仅包含通过 :ref:`add_user_signal` 添加的信号。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_is_blocking_signals: .. rst-class:: classref-method :ref:`bool` **is_blocking_signals** **(** **)** |const| 如果该对象正在阻止发出信号，则返回 ``true``\ 。见 :ref:`set_block_signals`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_is_class: .. rst-class:: classref-method :ref:`bool` **is_class** **(** :ref:`String` class **)** |const| 如果该对象继承自给定的 ``class`` 则返回 ``true``\ 。另见 :ref:`get_class`\ 。 .. tabs:: .. code-tab:: gdscript var sprite2d = Sprite2D.new() sprite2d.is_class("Sprite2D") # 返回 true sprite2d.is_class("Node") # 返回 true sprite2d.is_class("Node3D") # 返回 false .. code-tab:: csharp var sprite2D = new Sprite2D(); sprite2D.IsClass("Sprite2D"); // 返回 true sprite2D.IsClass("Node"); // 返回 true sprite2D.IsClass("Node3D"); // 返回 false \ **注意：**\ 此方法忽略对象脚本中的 ``class_name`` 声明。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_is_connected: .. rst-class:: classref-method :ref:`bool` **is_connected** **(** :ref:`StringName` signal, :ref:`Callable` callable **)** |const| 如果给定的 ``signal`` 名称和 ``callable`` 之间存在连接，则返回 ``true``\ 。 \ **注意：**\ 在 C# 中，在引用 Godot 内置方法时，\ ``signal`` 必须是 snake_case。最好使用 ``SignalName`` 类中公开的名称，以避免在每次调用时分配一个新的 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_is_queued_for_deletion: .. rst-class:: classref-method :ref:`bool` **is_queued_for_deletion** **(** **)** |const| 如果为该对象调用了 :ref:`Node.queue_free` 方法，则返回 ``true``\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_notification: .. rst-class:: classref-method void **notification** **(** :ref:`int` what, :ref:`bool` reversed=false **)** 将给定的 ``what`` 通知发送给对象继承的所有类，触发对 :ref:`_notification` 的调用，从最高祖先（\ **Object** 类）开始，向下一直到对象的脚本。 如果 ``reversed`` 为 ``true``\ ，则调用顺序会被颠倒。 .. tabs:: .. code-tab:: gdscript var player = Node2D.new() player.set_script(load("res://player.gd")) player.notification(NOTIFICATION_ENTER_TREE) # 调用顺序是 Object -> Node -> Node2D -> player.gd。 player.notification(NOTIFICATION_ENTER_TREE, true) # 调用顺序是 player.gd -> Node2D -> Node -> Object。 .. code-tab:: csharp var player = new Node2D(); player.SetScript(GD.Load("res://player.gd")); player.Notification(NotificationEnterTree); // 调用顺序是 GodotObject -> Node -> Node2D -> player.gd。 player.Notification(NotificationEnterTree, true); // 调用顺序是 player.gd -> Node2D -> Node -> GodotObject。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_notify_property_list_changed: .. rst-class:: classref-method void **notify_property_list_changed** **(** **)** 发出 :ref:`property_list_changed` 信号。这主要是用来刷新编辑器，以让检查器和编辑器插件被正确更新。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_property_can_revert: .. rst-class:: classref-method :ref:`bool` **property_can_revert** **(** :ref:`StringName` property **)** |const| 如果给定的属性 ``property`` 有自定义的默认值，则返回 ``true``\ 。请使用 :ref:`property_get_revert` 获取 ``property`` 的默认值。 \ **注意：**\ “检查器”面板会使用这个方法来显示恢复图标。该对象必须实现 :ref:`_property_can_revert` 来自定义默认值。如果未实现 :ref:`_property_can_revert`\ ，则这个方法返回 ``false``\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_property_get_revert: .. rst-class:: classref-method :ref:`Variant` **property_get_revert** **(** :ref:`StringName` property **)** |const| 返回给定的属性 ``property`` 的自定义默认值。请使用 :ref:`property_can_revert` 检查 ``property`` 是否有自定义的默认值。 \ **注意：**\ “检查器”面板会使用这个方法来显示恢复图标。该对象必须实现 :ref:`_property_get_revert` 来自定义默认值。如果未实现 :ref:`_property_get_revert`\ ，则这个方法返回 ``null``\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_remove_meta: .. rst-class:: classref-method void **remove_meta** **(** :ref:`StringName` name **)** 从对象的元数据中移除名称为 ``name`` 的条目。另请参阅 :ref:`has_meta`\ 、\ :ref:`get_meta`\ 、和 :ref:`set_meta`\ 。 \ **注意：**\ 元数据的名称必须是符合 :ref:`StringName.is_valid_identifier` 的有效标识符。 \ **注意：**\ 名称以下划线（\ ``_``\ ）开头的元数据仅供编辑器使用。仅供编辑器使用的元数据不会在“检查器”中显示，虽然仍然能够被这个方法找到，但是不应该进行编辑。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_set: .. rst-class:: classref-method void **set** **(** :ref:`StringName` property, :ref:`Variant` value **)** 将给定属性 ``property`` 的值分配为 ``value``\ 。如果该属性不存在，或者给定 ``value`` 的类型不匹配，则不会发生任何事情。 .. tabs:: .. code-tab:: gdscript var node = Node2D.new() node.set("global_scale", Vector2(8, 2.5)) print(node.global_scale) # 输出 (8, 2.5) .. code-tab:: csharp var node = new Node2D(); node.Set("global_scale", new Vector2(8, 2.5)); GD.Print(node.GlobalScale); // 输出 Vector2(8, 2.5) \ **注意：**\ 在 C# 中引用内置 Godot 属性时 ``property`` 必须为 snake_case 蛇形大小写。请优先使用 ``PropertyName`` 类中暴露的名称，避免每次调用都重新分配一个 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_set_block_signals: .. rst-class:: classref-method void **set_block_signals** **(** :ref:`bool` enable **)** 如果设置为 ``true``\ ，这该对象将无法发出信号。因此，\ :ref:`emit_signal` 和信号连接将不起作用，直到该属性被设置为 ``false``\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_set_deferred: .. rst-class:: classref-method void **set_deferred** **(** :ref:`StringName` property, :ref:`Variant` value **)** 在当前帧的末尾，将给定属性 ``property`` 的值分配为 ``value``\ 。等价于通过 :ref:`call_deferred` 调用 :ref:`set`\ 。 .. tabs:: .. code-tab:: gdscript var node = Node2D.new() add_child(node) node.rotation = 45.0 node.set_deferred("rotation", 90.0) print(node.rotation) # 输出 45.0 await get_tree().process_frame print(node.rotation) # 输出 90.0 .. code-tab:: csharp var node = new Node2D(); node.Rotation = 45f; node.SetDeferred("rotation", 90f); GD.Print(node.Rotation); // 输出 45.0 await ToSignal(GetTree(), SceneTree.SignalName.ProcessFrame); GD.Print(node.Rotation); // 输出 90.0 \ **注意：**\ 在 C# 中引用内置 Godot 属性时 ``property`` 必须为 snake_case 蛇形大小写。请优先使用 ``PropertyName`` 类中暴露的名称，避免每次调用都重新分配一个 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_set_indexed: .. rst-class:: classref-method void **set_indexed** **(** :ref:`NodePath` property_path, :ref:`Variant` value **)** 将由属性路径 ``property_path`` 标识的属性的值分配为 ``value``\ 。该路径应为相对于这个对象的 :ref:`NodePath`\ ，可以使用英文冒号（\ ``:``\ ）访问内嵌属性。 .. tabs:: .. code-tab:: gdscript var node = Node2D.new() node.set_indexed("position", Vector2(42, 0)) node.set_indexed("position:y", -10) print(node.position) # 输出 (42, -10) .. code-tab:: csharp var node = new Node2D(); node.SetIndexed("position", new Vector2(42, 0)); node.SetIndexed("position:y", -10); GD.Print(node.Position); // 输出 (42, -10) \ **注意：**\ 在 C# 中引用内置 Godot 属性时 ``property_path`` 必须为 snake_case 蛇形大小写。请优先使用 ``PropertyName`` 类中暴露的名称，避免每次调用都重新分配一个 :ref:`StringName`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_set_message_translation: .. rst-class:: classref-method void **set_message_translation** **(** :ref:`bool` enable **)** 如果设置为 ``true``\ ，则允许对象使用 :ref:`tr` 和 :ref:`tr_n` 翻译消息。该属性默认启用。另请参阅 :ref:`can_translate_messages`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_set_meta: .. rst-class:: classref-method void **set_meta** **(** :ref:`StringName` name, :ref:`Variant` value **)** 添加或更改对象元数据中名称为 ``name`` 的条目。元数据值 ``value`` 可以是任何 :ref:`Variant`\ ，尽管某些类型无法正确序列化。 如果 ``value`` 为 ``null``\ ，则该条目被移除。等价于使用 :ref:`remove_meta`\ 。另见 :ref:`has_meta` 和 :ref:`get_meta`\ 。 \ **注意：**\ 元数据的名称必须是符合 :ref:`StringName.is_valid_identifier` 的有效标识符。 \ **注意：**\ 名称以下划线（\ ``_``\ ）开头的元数据仅供编辑器使用。仅供编辑器使用的元数据不会在“检查器”中显示，虽然仍然能够被这个方法找到，但是不应该进行编辑。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_set_script: .. rst-class:: classref-method void **set_script** **(** :ref:`Variant` script **)** 将脚本 ``script`` 附加至该对象，并进行实例化。因此会调用该脚本的 :ref:`_init`\ 。\ :ref:`Script` 可用于扩展对象的功能。 如果已存在脚本，则该脚本的实例会被分离，其属性值和状态会丢失。仍会保留内置属性的值。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_to_string: .. rst-class:: classref-method :ref:`String` **to_string** **(** **)** 返回表示对象的 :ref:`String`\ 。默认为 ``""``\ 。覆盖 :ref:`_to_string` 以自定义对象的字符串表示形式。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_tr: .. rst-class:: classref-method :ref:`String` **tr** **(** :ref:`StringName` message, :ref:`StringName` context="" **)** |const| 使用项目设置中配置的翻译目录，翻译一个 ``message``\ 。可以进一步指定 ``context`` 来帮助翻译。 如果 :ref:`can_translate_messages` 为 ``false``\ ，或者没有翻译可用，则该方法将返回 ``message`` 而不做任何更改。请参阅 :ref:`set_message_translation`\ 。 有关详细示例，请参阅\ :doc:`《国际化游戏》 <../tutorials/i18n/internationalizing_games>`\ 。 .. rst-class:: classref-item-separator ---- .. _class_Object_method_tr_n: .. rst-class:: classref-method :ref:`String` **tr_n** **(** :ref:`StringName` message, :ref:`StringName` plural_message, :ref:`int` n, :ref:`StringName` context="" **)** |const| 使用项目设置中配置的翻译目录，翻译一个 ``message`` 或 ``plural_message``\ 。可以进一步指定 ``context`` 来帮助翻译。 如果 :ref:`can_translate_messages` 为 ``false``\ ，或者没有翻译可用，则该方法将返回 ``message`` 或 ``plural_message``\ ，而不做任何更改。请参阅 :ref:`set_message_translation`\ 。 \ ``n`` 是消息主题的数字或数量。它被翻译系统用来获取当前语言的正确复数形式。 有关详细示例，请参阅\ :doc:`《使用 gettext 进行本地化》 <../tutorials/i18n/localization_using_gettext>`\ 。 \ **注意：**\ 负数和 :ref:`float` 数字可能不适用于某些可数科目。建议使用 :ref:`tr` 处理这些情况。 .. |virtual| replace:: :abbr:`virtual (本方法通常需要用户覆盖才能生效。)` .. |const| replace:: :abbr:`const (本方法没有副作用。不会修改该实例的任何成员变量。)` .. |vararg| replace:: :abbr:`vararg (本方法除了在此处描述的参数外，还能够继续接受任意数量的参数。)` .. |constructor| replace:: :abbr:`constructor (本方法用于构造某个类型。)` .. |static| replace:: :abbr:`static (调用本方法无需实例，所以可以直接使用类名调用。)` .. |operator| replace:: :abbr:`operator (本方法描述的是使用本类型作为左操作数的有效操作符。)` .. |bitfield| replace:: :abbr:`BitField (这个值是由下列标志构成的位掩码整数。)`