JSON

用于创建和解析 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.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)