Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

JSON

继承： Resource < RefCounted < Object

用于创建和解析 JSON 数据的辅助类。

描述

JSON 类允许所有数据类型与 JSON 字符串相互转换。可用于将数据序列化，例如保存到文件或通过网络发送。

stringify() 用于将任何数据类型转换为 JSON 字符串。

parse() 用于将任何现有的 JSON 数据转换为可以在 Godot 中使用的 Variant。如果解析成功，使用 data 检索 Variant，并使用 @GlobalScope.typeof() 检查 Variant 的类型是否符合你的预期。JSON 对象被转换为 Dictionary，但 JSON 数据可用于存储 Array、数字、String，甚至只是一个布尔值。

var data_to_send = ["a", "b", "c"]
var json_string = JSON.stringify(data_to_send)
# 保存数据
# ...
# 检索数据
var json = JSON.new()
var error = json.parse(json_string)
if error == OK:
    var data_received = json.data
    if typeof(data_received) == TYPE_ARRAY:
        print(data_received) # 输出该数组。
    else:
        print("意外数据")
else:
    print("JSON 解析错误：", json.get_error_message(), " 位于 ", json_string, " 行号 ", json.get_error_line())

你也可以使用静态的 parse_string() 方法解析字符串，但该方法不会处理错误。

var data = JSON.parse_string(json_string) # 如果解析失败则返回 null。

注意：两种解析方式都不完全符合 JSON 规范：

• 数组或对象中的尾随逗号将被忽略，而不是引起解析器错误。

• 换行符和制表符在字符串文字中被接受，并被视为它们相应的转义序列 \n 和 \t。

• 使用 String.to_float() 解析数字，这通常比 JSON 规范更宽松。

• 某些错误不会导致解析器错误，例如 Unicode 序列无效，但是该字符串会被清理并将错误记录到控制台。

属性

Variant

data

null

方法

Variant	from_native(variant: Variant, full_objects: bool = false) static
int	get_error_line() const
String	get_error_message() const
String	get_parsed_text() const
Error	parse(json_text: String, keep_text: bool = false)
Variant	parse_string(json_string: String) static
String	stringify(data: Variant, indent: String = "", sort_keys: bool = true, full_precision: bool = false) static
Variant	to_native(json: Variant, allow_objects: bool = false) static

---

属性说明

Variant data = null 🔗

• void set_data(value: Variant)

• Variant get_data()

包含解析到的 JSON 数据，类型为 Variant。

---

方法说明

Variant from_native(variant: Variant, full_objects: bool = false) static 🔗

将引擎原生类型转换为 JSON 兼容类型。

出于安全原因，默认会忽略对象，除非 full_objects 为 true。

将原生值转换为 JSON 字符串的方法如下：

func encode_data(value, full_objects = false):
    return JSON.stringify(JSON.from_native(value, full_objects))

---

int get_error_line() const 🔗

如果上一次调用 parse() 成功，则返回 0，否则返回解析失败的行号。

---

String get_error_message() const 🔗

如果上一次调用 parse() 成功，则返回空字符串，否则返回失败时的错误消息。

---

String get_parsed_text() const 🔗

返回由 parse() 解析的文本（要求向 parse() 传递 keep_text）。

---

Error parse(json_text: String, keep_text: bool = false) 🔗

尝试解析提供的 json_text。

返回 Error。如果解析成功则返回 @GlobalScope.OK，并且可以使用 data 检索该结果。如果不成功，请使用 get_error_line() 和 get_error_message() 来识别失败的原因。

如果想要自定义错误处理，可以使用的 parse_string() 的非静态版本。

可选的 keep_text 参数会让解析器保留原始文本的副本。该文本稍后可以使用 get_parsed_text() 函数获取，并在保存资源时使用（而不是从 data 生成新文本）。

---

Variant parse_string(json_string: String) static 🔗

试图解析提供的 json_string，并返回解析后的数据。如果解析失败，返回 null。

---

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

将 Variant 变量转换为 JSON 文本并返回结果。可用于将数据进行序列化保存或通过网络发送。

注意：JSON 规范没有定义整数和浮点数类型，只有一个数字类型。因此，将 Variant 转换为 JSON 文本会将所有数字值转换为 float 类型。

注意：如果 full_precision 为 true，则在字符串化浮点数时，除可靠数字外，还将对不可靠数字进行字符串化，以保证准确解码。

indent 参数控制是否缩进以及如何缩进，输出时应该有缩进的地方会用到它的值。甚至可以使用空格 " " 缩进。\t 和 \n 可用于制表符缩进，或分别为每个缩进换行。

警告：JSON 不支持非有限数。任何出现的 @GDScript.INF 都将被替换为 1e99999，负数 @GDScript.INF 将被替换为 -1e99999，但大多数 JSON 解析器会将其正确解析为无穷大。@GDScript.NAN 将被替换为 null，并且 JSON 解析器不会将其解析为 NaN。如果你需要处理非有限数，请考虑先使用 from_native() 方法处理你的数据。

示例输出：

## JSON.stringify(my_dictionary)
{"name":"my_dictionary","version":"1.0.0","entities":[{"name":"entity_0","value":"value_0"},{"name":"entity_1","value":"value_1"}]}

## JSON.stringify(my_dictionary, "\t")
{
    "name": "my_dictionary",
    "version": "1.0.0",
    "entities": [
        {
            "name": "entity_0",
            "value": "value_0"
        },
        {
            "name": "entity_1",
            "value": "value_1"
        }
    ]
}

## JSON.stringify(my_dictionary, "...")
{
..."name": "my_dictionary",
..."version": "1.0.0",
..."entities": [
......{
........."name": "entity_0",
........."value": "value_0"
......},
......{
........."name": "entity_1",
........."value": "value_1"
......}
...]
}

---

Variant to_native(json: Variant, allow_objects: bool = false) static 🔗

将使用 from_native() 创建的 JSON 兼容值转换回引擎原生类型。

出于安全原因，默认会忽略对象，除非 allow_objects 为 true。

将 JSON 字符串转换回原生值的方法如下：

func decode_data(string, allow_objects = false):
    return JSON.to_native(JSON.parse_string(string), allow_objects)