Up to date
This page is up to date for Godot 4.3.
If you still find outdated information, please open an issue.
變體
有關 Variant 的一般詳細說明，請參閱 Variant <class_Variant> 檔案頁面。
Godot.Variant is used to represent Godot's native Variant type. Any
Variant-compatible type can be converted from/to it.
We recommend avoiding Godot.Variant unless it is necessary to interact with untyped engine APIs.
Take advantage of C#'s type safety when possible.
Converting from a Variant-compatible C# type to Godot.Variant can be done using implicit
conversions. There are also CreateFrom method overloads and the generic Variant.From<T>
methods. Only the syntax is different: the behavior is the same.
int x = 42;
Variant numberVariant = x;
Variant helloVariant = "Hello, World!";
Variant numberVariant2 = Variant.CreateFrom(x);
Variant numberVariant3 = Variant.From(x);
Implicit conversions to Godot.Variant make passing variants as method arguments very convenient.
For example, the third argument of tween_property
specifying the final color of the tween is a Godot.Variant.
Tween tween = CreateTween();
tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);
Converting from Godot.Variant to a C# type can be done using explicit conversions. There are
also Variant.As{TYPE} methods and the generic Variant.As<T> method. All of these behave the
same.
int number = (int)numberVariant;
string hello = (string)helloVariant;
int number2 = numberVariant.As<int>();
int number3 = numberVariant.AsInt32();
備註
The Variant.As{TYPE} methods are typically named after C# types (Int32), not C# keywords
(int).
If the Variant type doesn't match the conversion target type, the consequences vary depending on the source and target values.
The conversion may examine the value and return a similar but potentially unexpected value of the target type. For example, the string
"42a"may be converted to the integer42.The default value of the target type may be returned.
An empty array may be returned.
An exception may be thrown.
Converting to the correct type avoids complicated behavior and should be preferred.
The Variant.Obj property returns a C# object with the correct value for any variant. This
may be useful when the type of Variant is completely unknown. However, when possible, prefer more
specific conversions. Variant.Obj evaluates a switch on Variant.VariantType and it may
not be necessary. Also, if the result is a value type, it is boxed.
For example, if the potential for Variant.As<MyNode>() to throw an invalid cast exception isn't
acceptable, consider using a Variant.As<GodotObject>() is MyNode n type pattern instead.
備註
Since the Variant type in C# is a struct, it can't be null. To create a "null"
Variant, use the default keyword or the Godot.Variant parameterless constructor.
自定變數型別
A Variant-compatible type can be converted to and from a Godot.Variant.
These C# types are Variant-compatible:
所有「內建值型別 <https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/built-in-types-table>」_，除了「decimal」 、「nint」和「nuint」。
: String在「Godot.Collections」命名空間中定義的集合型別。
Variant 型別及其等效 C# 型別的完整列表：
變體 |
型別 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
警告
Godot uses 64-bit integers and floats in Variant. Smaller integer and float types
such as int, short and float are supported since they can fit in the
bigger type. Be aware that when a conversion is performed, using the wrong
type will result in potential precision loss.
警告
列舉受“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.
}