最后更新日期：2026-04-16

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

JSON.stringify

定义

JSON.stringify 把 Godot 的数据（字典、数组、数字等）转换成 JSON 格式的文本字符串——和 Parse() 正好是反过来的操作。

打个比方：Parse() 是把外文翻译成中文，Stringify() 就是把中文翻译成外文。你手头有一个 Godot 的字典（比如 {"name": "小明", "age": 18}），Stringify() 会把它变成一段标准的 JSON 文本 '{"name":"小明","age":18}'，这样就可以保存到文件或发送给服务器了。

在游戏开发中，这个功能常用于：保存游戏数据到文件、发送数据给服务器、导出配置信息等。

函数签名

C#

// Json.Stringify 将 Godot 数据转换为 JSON 字符串
public static string Stringify(Variant data, string indent = "", bool sortKeys = true, bool fullPrecision = false)

GDScript

static func stringify(data: Variant, indent: String = "", sort_keys: bool = true, full_precision: bool = false) -> String

参数说明

参数	类型	必需	默认值	说明
data	Variant	是	—	要转换的数据，支持字典、数组、字符串、数字、布尔值等
indent	String	否	""	缩进字符串。传入 " " 或 "\t" 可以让输出更易读
sortKeys	bool	否	true	是否按字母顺序排列字典的键
fullPrecision	bool	否	false	是否保留浮点数的完整精度

返回值

String —— 转换后的 JSON 格式字符串。

代码示例

基础用法：把字典转换为 JSON 字符串

C#

using Godot;

public partial class MyScene : Node
{
    public override void _Ready()
    {
        var playerData = new Godot.Collections.Dictionary
        {
            ["name"] = "小明",
            ["level"] = 12,
            ["health"] = 85.5,
            ["is_alive"] = true
        };

        string jsonText = Json.Stringify(playerData);
        GD.Print(jsonText);
        // 运行结果: {"health":85.5,"is_alive":true,"level":12,"name":"小明"}
        // 注意：键默认按字母顺序排列
    }
}

GDScript

extends Node

func _ready():
    var player_data = {
        "name": "小明",
        "level": 12,
        "health": 85.5,
        "is_alive": true
    }

    var json_text = JSON.stringify(player_data)
    print(json_text)
    # 运行结果: {"health":85.5,"is_alive":true,"level":12,"name":"小明"}
    # 注意：键默认按字母顺序排列

实际场景：保存游戏数据到文件

C#

using Godot;

public partial class SaveManager : Node
{
    public void SaveGame(string filePath, string playerName, int level, float health)
    {
        var saveData = new Godot.Collections.Dictionary
        {
            ["player_name"] = playerName,
            ["level"] = level,
            ["health"] = health,
            ["save_time"] = Time.GetUnixTimeFromSystem()
        };

        // 转换为带缩进的 JSON（方便阅读）
        string jsonText = Json.Stringify(saveData, indent: "  ");

        var file = FileAccess.Open(filePath, FileAccess.ModeFlags.Write);
        if (file != null)
        {
            file.StoreString(jsonText);
            file.Close();
            GD.Print("游戏已保存");
            // 运行结果: 游戏已保存
        }
    }
}

GDScript

extends Node

func save_game(file_path: String, player_name: String, level: int, health: float):
    var save_data = {
        "player_name": player_name,
        "level": level,
        "health": health,
        "save_time": Time.get_unix_time_from_system()
    }

    # 转换为带缩进的 JSON（方便阅读）
    var json_text = JSON.stringify(save_data, "  ")

    var file = FileAccess.open(file_path, FileAccess.WRITE)
    if file:
        file.store_string(json_text)
        file.close()
        print("游戏已保存")
        # 运行结果: 游戏已保存

进阶用法：嵌套数据和格式化输出

C#

using Godot;

public partial class LevelExporter : Node
{
    public override void _Ready()
    {
        var levelData = new Godot.Collections.Dictionary
        {
            ["level_name"] = "第一关",
            ["enemies"] = new Godot.Collections.Array
            {
                new Godot.Collections.Dictionary { ["type"] = "skeleton", ["hp"] = 30 },
                new Godot.Collections.Dictionary { ["type"] = "goblin", ["hp"] = 20 }
            },
            ["rewards"] = new Godot.Collections.Dictionary
            {
                ["gold"] = 500,
                ["exp"] = 100
            }
        };

        // 无缩进（紧凑格式，适合传输）
        string compact = Json.Stringify(levelData);
        GD.Print("紧凑格式:");
        GD.Print(compact);
        // 运行结果: {"enemies":[{"hp":30,"type":"skeleton"},{"hp":20,"type":"goblin"}],...}

        // 带缩进（美化格式，适合文件存储和阅读）
        string pretty = Json.Stringify(levelData, indent: "  ");
        GD.Print("\n美化格式:");
        GD.Print(pretty);
        // 运行结果:
        // {
        //   "enemies": [
        //     {
        //       "hp": 30,
        //       "type": "skeleton"
        //     },
        //     {
        //       "hp": 20,
        //       "type": "goblin"
        //     }
        //   ],
        //   "level_name": "第一关",
        //   "rewards": {
        //     "exp": 100,
        //     "gold": 500
        //   }
        // }
    }
}

GDScript

extends Node

func _ready():
    var level_data = {
        "level_name": "第一关",
        "enemies": [
            {"type": "skeleton", "hp": 30},
            {"type": "goblin", "hp": 20}
        ],
        "rewards": {
            "gold": 500,
            "exp": 100
        }
    }

    # 无缩进（紧凑格式，适合传输）
    var compact = JSON.stringify(level_data)
    print("紧凑格式:")
    print(compact)
    # 运行结果: {"enemies":[{"hp":30,"type":"skeleton"},{"hp":20,"type":"goblin"}],...}

    # 带缩进（美化格式，适合文件存储和阅读）
    var pretty = JSON.stringify(level_data, "  ")
    print("\n美化格式:")
    print(pretty)
    # 运行结果:
    # {
    #   "enemies": [
    #     {
    #       "hp": 30,
    #       "type": "skeleton"
    #     },
    #     {
    #       "hp": 20,
    #       "type": "goblin"
    #     }
    #   ],
    #   "level_name": "第一关",
    #   "rewards": {
    #     "exp": 100,
    #     "gold": 500
    #   }
    # }

注意事项

• 不是所有 Godot 类型都能转换：基础类型（字典、数组、字符串、数字、布尔、null）可以，但 Vector2、Color 等引擎类型不能直接序列化，需要先手动转换为字典。
• 键默认按字母排序：sortKeys 默认为 true，输出的 JSON 中字典的键会按字母顺序排列。如果你需要保持原始顺序，设为 false。
• indent 参数让输出更易读：传入 " "（两个空格）或 "\t"（制表符）可以得到格式化的 JSON，方便人类阅读。如果不传，输出是紧凑的单行格式。
• 和 Parse() 是一对：Stringify() 把数据变成字符串，Parse() 把字符串变回数据。两者配合使用可以实现完整的序列化/反序列化。
• 循环引用会导致无限递归：如果字典中有循环引用（A 引用 B，B 又引用 A），Stringify() 会崩溃。注意避免这种数据结构。