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

str_to_var

定义

str_to_var() 是 var_to_str() 的逆操作——它把一段之前序列化好的文本还原回原始的数据类型。

继续用快递的比喻：你朋友收到了你发过去的菜单照片（文本），现在需要把它变回真正的菜单（数据结构）。str_to_var() 就是这个"还原"的过程，它把文字中的数字、字符串、数组、字典等信息重新变回 Godot 可以直接使用的数据。

函数签名

C#

// C# 中没有直接等价函数
// 请使用 Json.Parse 来解析 JSON 文本
var json = new Json();
Error err = json.Parse(jsonString);
var data = json.Data;

GDScript

func str_to_var(string: String) -> Variant

参数说明

参数	类型	必需	说明
string	String	是	由 var_to_str() 生成的序列化文本

返回值

Variant —— 反序列化后的原始值。数据类型和结构与序列化之前完全一致。

代码示例

基础用法：从文本还原数据

C#

using Godot;

public partial class StrToVarExample : Node
{
    public override void _Ready()
    {
        // C# 中使用 JSON 解析
        string jsonText = "{\"name\":\"Godot\",\"version\":4}";
        var json = new Json();
        Error err = json.Parse(jsonText);

        if (err == Error.Ok)
        {
            var data = (Godot.Collections.Dictionary)json.Data;
            GD.Print($"名称: {data["name"]}, 版本: {data["version"]}");
            // 运行结果: 名称: Godot, 版本: 4
        }
    }
}

GDScript

extends Node

func _ready():
    # 从文本还原不同类型的值
    var num = str_to_var("42")
    print("数字: ", num, " 类型: ", typeof(num))
    # 运行结果: 数字: 42 类型: 2 (TYPE_INT)

    var text = str_to_var("\"Hello\"")
    print("文本: ", text, " 类型: ", typeof(text))
    # 运行结果: 文本: Hello 类型: 4 (TYPE_STRING)

    # 从文本还原数组和字典
    var arr = str_to_var("[1, 2, 3]")
    print("数组: ", arr)
    # 运行结果: 数组: [1, 2, 3]

    var dict = str_to_var("{\"name\": \"Godot\", \"version\": 4}")
    print("字典: ", dict)
    # 运行结果: 字典: { "name": "Godot", "version": 4 }

实际场景：读取文本配置文件

C#

using Godot;

public partial class TextConfigLoader : Node
{
    public void LoadPlayerConfig()
    {
        // 模拟从文本文件读取的内容
        string configText = @"{
            ""name"": ""勇者"",
            ""level"": 5,
            ""hp"": 100,
            ""items"": [""剑"", ""盾"", ""药水""]
        }";

        var json = new Json();
        Error err = json.Parse(configText);

        if (err == Error.Ok)
        {
            var config = (Godot.Collections.Dictionary)json.Data;
            GD.Print($"角色: {config["name"]}");
            GD.Print($"等级: {config["level"]}");
            GD.Print($"HP: {config["hp"]}");
        }
    }

    public override void _Ready()
    {
        LoadPlayerConfig();
    }
}

GDScript

extends Node

func load_player_config() -> void:
    # 模拟从文本文件读取的内容
    var config_text = "{
        \"name\": \"勇者\",
        \"level\": 5,
        \"hp\": 100,
        \"items\": [\"剑\", \"盾\", \"药水\"]
    }"

    # 用 str_to_var 还原为字典
    var config = str_to_var(config_text)

    print("角色: ", config["name"])
    print("等级: ", config["level"])
    print("HP: ", config["hp"])
    # 运行结果:
    # 角色: 勇者
    # 等级: 5
    # HP: 100

func _ready():
    load_player_config()

进阶用法：网络消息解析

C#

using Godot;

public partial class NetworkParser : Node
{
    public void ParseMessage(string message)
    {
        var json = new Json();
        Error err = json.Parse(message);

        if (err != Error.Ok)
        {
            GD.PrintErr($"消息格式错误: {json.GetErrorMessage()}");
            return;
        }

        var data = (Godot.Collections.Dictionary)json.Data;
        string type = (string)data["type"];

        switch (type)
        {
            case "chat":
                GD.Print($"[{data["sender"]}]: {data["text"]}");
                break;
            case "move":
                GD.Print($"移动到: ({data["x"]}, {data["y"]})");
                break;
        }
    }

    public override void _Ready()
    {
        ParseMessage("{\"type\":\"chat\",\"sender\":\"勇者\",\"text\":\"你好!\"}");
        // 运行结果: [勇者]: 你好!

        ParseMessage("{\"type\":\"move\",\"x\":100,\"y\":200}");
        // 运行结果: 移动到: (100, 200)
    }
}

GDScript

extends Node

func parse_message(message: String) -> void:
    var data = str_to_var(message)
    if data == null:
        push_error("消息格式错误")
        return

    match data["type"]:
        "chat":
            print("[%s]: %s" % [data["sender"], data["text"]])
        "move":
            print("移动到: (%s, %s)" % [data["x"], data["y"]])

func _ready():
    parse_message('{"type":"chat","sender":"勇者","text":"你好!"}')
    # 运行结果: [勇者]: 你好!

    parse_message('{"type":"move","x":100,"y":200}')
    # 运行结果: 移动到: (100, 200)

注意事项

1. 必须与 var_to_str() 配对使用：用 var_to_str() 生成的文本，必须用 str_to_var() 还原。不能混用 bytes_to_var() 或 JSON.parse()。

2. 格式兼容性：str_to_var() 也能解析格式兼容的文本（如 [1, 2, 3] 或 {"key": "value"}），不一定非得由 var_to_str() 生成。这让你可以手动编写配置文本。

3. 解析失败返回 null：如果传入的文本格式不正确，str_to_var() 会返回 null 而不是崩溃。建议在使用结果前检查是否为 null。

4. C# 中推荐使用 JSON：C# 中没有 str_to_var() 的直接等价。推荐使用 Json 类的 Parse() 方法来解析 JSON 文本。