Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

JSON¶

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

描述¶

JSON 允许所有数据类型与 JSON 字符串相互转换。这对于序列化数据以保存到文件或通过网络发送很有用。

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

parse 用于将任何现有的 JSON 数据转换为可以在 Godot 中使用的 Variant。如果解析成功，使用 data 检索 Variant，并使用 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) # 输出 array
    else:
        print("Unexpected data")
else:
    print("JSON Parse Error: ", json.get_error_message(), " in ", json_string, " at line ", 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

方法¶

int	get_error_line ( ) const
String	get_error_message ( ) const
String	get_parsed_text ( ) const
Error	parse ( String json_text, bool keep_text=false )
Variant	parse_string ( String json_string ) static
String	stringify ( Variant data, String indent="", bool sort_keys=true, bool full_precision=false ) static

属性说明¶

Variant data = null

void set_data ( Variant value )
Variant get_data ( )

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

方法说明¶

int get_error_line ( ) const

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

String get_error_message ( ) const

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

String get_parsed_text ( ) const

只要该函数被指示以保留该文本，就返回由 parse 解析的文本。

Error parse ( String json_text, bool keep_text=false )

尝试解析提供的 json_text。

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

如果想要自定义错误处理，可以使用的 parse_string 的非静态变体。

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

Variant parse_string ( String json_string ) static

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

String stringify ( Variant data, String indent="", bool sort_keys=true, bool full_precision=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"
......}
...]
}