最后同步日期：2026-04-15 | Godot 官方原文 — type_convert

type_convert

定义

type_convert() 是一个万能翻译器——你给它一个值，再告诉它"请把这个值翻译成整数"或者"翻译成字符串"，它就会尝试帮你完成转换。

想象你在国外旅行，手里有一张写着数字的纸条，你需要让当地人理解你的意思。你可以选择"翻译成英文"或者"翻译成法语"。type_convert() 就是这个翻译器：你把值交出去，指定目标语言（类型），它负责翻译。如果翻译不了（比如把文字"hello"翻译成整数），它会给你一个默认值（整数的话默认是 0）。

函数签名

C#

// C# 是强类型语言，没有直接的 type_convert() 函数
// 请使用 C# 内置的类型转换语法：
// 隐式转换：int -> float（自动完成）
// 显式转换：(int)myFloat（强制转换）
// 方法转换：int.TryParse("123", out int result)
// 或者使用 Convert 类：Convert.ToInt32("123")

GDScript

func type_convert(variant: Variant, type: int) -> Variant

参数说明

参数	类型	必需	说明
variant	Variant	是	要转换的值，可以是任意类型
type	int	是	目标类型的编号，使用类型常量指定，如 TYPE_INT、TYPE_STRING、TYPE_FLOAT 等

常用的类型常量：

常量	编号	对应类型
TYPE_NIL	0	空（null）
TYPE_BOOL	1	布尔值
TYPE_INT	2	整数
TYPE_FLOAT	3	浮点数
TYPE_STRING	4	字符串
TYPE_VECTOR2	5	二维向量
TYPE_VECTOR3	7	三维向量
TYPE_ARRAY	15	数组
TYPE_DICTIONARY	17	字典

返回值

Variant —— 转换后的值。如果转换失败，返回目标类型的默认值：

目标类型	转换失败时的默认值
整数（TYPE_INT）	0
浮点数（TYPE_FLOAT）	0.0
字符串（TYPE_STRING）	""（空字符串）
布尔值（TYPE_BOOL）	false
数组（TYPE_ARRAY）	[]（空数组）

代码示例

C#

using Godot;

public partial class TypeConvertExample : Node
{
    public override void _Ready()
    {
        // C# 使用内置语法进行类型转换

        // 字符串转整数
        string _strNumber = "42";
        int _parsedInt = int.Parse(_strNumber);  // 42
        GD.Print(_parsedInt);

        // 安全的字符串转整数（不会抛异常）
        string _strMaybe = "hello";
        if (int.TryParse(_strMaybe, out int _result))
        {
            GD.Print($"转换成功: {_result}");
        }
        else
        {
            GD.Print("转换失败，不是有效的整数");
        }

        // 整数转字符串
        int _score = 100;
        string _scoreText = _score.ToString();  // "100"

        // 浮点数转整数（截断小数部分）
        float _hp = 85.7f;
        int _hpInt = (int)_hp;  // 85

        // 使用 Convert 类进行各种转换
        string _boolStr = "true";
        bool _isReady = System.Convert.ToBoolean(_boolStr);  // true

        GD.Print($"分数: {_scoreText}, 生命值: {_hpInt}, 准备就绪: {_isReady}");
    }
}

GDScript

extends Node

func _ready():
	# 把字符串转换成整数
	var _text = "42"
	var _number = type_convert(_text, TYPE_INT)
	print(_number)         # 42
	print(typeof(_number)) # 2 (TYPE_INT)

	# 把整数转换成字符串
	var _score = 100
	var _score_text = type_convert(_score, TYPE_STRING)
	print(_score_text)         # "100"
	print(typeof(_score_text)) # 4 (TYPE_STRING)

	# 把浮点数转换成整数（截断小数部分）
	var _hp = 85.7
	var _hp_int = type_convert(_hp, TYPE_INT)
	print(_hp_int)  # 85

	# 转换失败的情况：把无法解析的文字转成整数
	var _bad_text = "hello"
	var _failed = type_convert(_bad_text, TYPE_INT)
	print(_failed)  # 0（转换失败，返回默认值）

	# 把整数转换成布尔值
	# 0 为 false，非零为 true
	var _value1 = type_convert(0, TYPE_BOOL)    # false
	var _value2 = type_convert(42, TYPE_BOOL)   # true
	print(_value1, " ", _value2)

	# 实际使用：处理从网络/文件读取的不确定类型数据
	var _raw_data = "3.14"
	var _pi = type_convert(_raw_data, TYPE_FLOAT)
	print(_pi)  # 3.14

注意事项

• C# 是强类型语言，没有 type_convert() 的直接等价。请使用 C# 内置的类型转换方式：int.Parse() / int.TryParse() 用于字符串转整数，.ToString() 用于任意类型转字符串，(int) 强制转换用于数值类型之间转换，Convert.ToXxx() 用于各种通用转换。
• GDScript 中 type_convert() 在转换失败时不会报错，而是静默返回目标类型的默认值。使用前最好先确认数据是否合理。
• 将浮点数转换为整数时，小数部分会被直接截断（不是四舍五入）。例如 3.9 会变成 3。如果需要四舍五入，请先使用 round() 函数。
• 将整数转换为布尔值时，0 变成 false，任何非零值都变成 true。
• 此函数与 typeof() 是一对好搭档：typeof() 告诉你"这个值是什么类型"，type_convert() 帮你"把这个值变成你想要的类型"。