Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
C# Variant¶
对于 Variant 的详细解释，请参阅 Variant 文档页面。
Godot.Variant 用于表示 Godot 的原生 Variant 类型。任何与 Variant 兼容的类型都可以和它进行转换。我们建议仅在与无类型的引擎 API 交互时使用 Godot.Variant 。尽可能利用 C# 的类型安全性。
任何 Variant.As{TYPE} 方法或通用的 Variant.As<T> 方法都可以用来将 Godot.Variant 转换为 C# 类型。由于 Godot.Variant 类型包含了所有支持类型的隐式转换，直接调用这些方法通常是不必要的。
使用 CreateFrom 方法的重载或通用的 Variant.From<T> 方法将 C# 类型转换为 Godot.Variant 。
备注
由于 C# 中的 Variant 类型是一个结构体，它不能为空。要创建一个 “null” Variant，使用 default 关键字或无参数构造函数。
Variant 兼容类型¶
除了
decimal、nint和nuint之外，所有的 内置值类型 。String。从 GodotObject 派生的类。
在
Godot.Collections命名空间中定义的集合类型。
Variant 类型的完整列表及其对应的 C# 类型：
Variant.Type |
C# 类型 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
警告
Godot 在 Variant 中使用 64 位的整数和浮点数。较小的整数和浮点数类型，如 int ， short 和 float ，也是支持的，因为它们可以放入更大的类型中。请注意，这里会进行隐式转换，所以使用错误的类型可能会导致精度损失。
警告
枚举类型由于其底层类型是整数类型，因此都与 Godot.Variant 兼容。但是，隐式转换不存在，枚举类型必须在转换为/从 Godot.Variant 之前手动转换为其底层的整数类型，或者使用通用的 Variant.As<T> 和 Variant.From<T> 方法来转换它们。
enum MyEnum { A, B, C }
Variant variant1 = (int)MyEnum.A;
MyEnum enum1 = (MyEnum)(int)variant1;
Variant variant2 = Variant.From(MyEnum.A);
MyEnum enum2 = variant2.As<MyEnum>();
在泛型上下文中使用 Variant¶
在使用泛型时，你可能希望限制泛型 T 类型仅为 Variant 兼容类型之一。这可以通过使用 [MustBeVariant] 特性来实现。
public void MethodThatOnlySupportsVariants<[MustBeVariant] T>(T onlyVariant)
{
// Do something with the Variant-compatible value.
}
结合泛型 Variant.From<T> 可以让你从一个泛型 T 类型的实例中获取一个 Godot.Variant 的实例。然后它可以用在任何只支持 Godot.Variant 结构体的 API 中。
public void Method1<[MustBeVariant] T>(T variantCompatible)
{
Variant variant = Variant.From(variantCompatible);
Method2(variant);
}
public void Method2(Variant variant)
{
// Do something with variant.
}
为了调用一个带有泛型参数的方法，该参数用 [MustBeVariant] 特性标注，值必须是 Variant 兼容类型或者带有 [MustBeVariant] 特性标注的泛型 T 类型。
public class ObjectDerivedClass : GodotObject { }
public class NonObjectDerivedClass { }
public void Main<[MustBeVariant] T1, T2>(T1 someGeneric1, T2 someGeneric2)
{
MyMethod(42); // Works because `int` is a Variant-compatible type.
MyMethod(new ObjectDerivedClass()); // Works because any type that derives from `GodotObject` is a Variant-compatible type.
MyMethod(new NonObjectDerivedClass()); // Does NOT work because the type is not Variant-compatible.
MyMethod(someGeneric1); // Works because `T1` is annotated with the `[MustBeVariant]` attribute.
MyMethod(someGeneric2); // Does NOT work because `T2` is NOT annotated with the `[MustBeVariant]` attribute.
}
public void MyMethod<[MustBeVariant] T>(T variant)
{
// Do something with variant.
}