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.

JSON

继承: Resource < RefCounted < Object

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

描述

The JSON class enables all data types to be converted to and from a JSON string. This is useful for serializing data, e.g. to save to a file or send over the network.

stringify is used to convert any data type into a JSON string.

parse is used to convert any existing JSON data into a Variant that can be used within Godot. If successfully parsed, use data to retrieve the Variant, and use @GlobalScope.typeof to check if the Variant's type is what you expect. JSON Objects are converted into a Dictionary, but JSON data can be used to store Arrays, numbers, Strings and even just a boolean.

var data_to_send = ["a", "b", "c"]
var json_string = JSON.stringify(data_to_send)
# Save data
# ...
# Retrieve data
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) # Prints the array.
    else:
        print("Unexpected data")
else:
    print("JSON Parse Error: ", json.get_error_message(), " in ", json_string, " at line ", json.get_error_line())

Alternatively, you can parse strings using the static parse_string method, but it doesn't handle errors.

var data = JSON.parse_string(json_string) # Returns null if parsing failed.

Note: Both parse methods do not fully comply with the JSON specification:

  • Trailing commas in arrays or objects are ignored, instead of causing a parser error.

  • New line and tab characters are accepted in string literals, and are treated like their corresponding escape sequences \n and \t.

  • Numbers are parsed using String.to_float which is generally more lax than the JSON specification.

  • Certain errors, such as invalid Unicode sequences, do not cause a parser error. Instead, the string is cleaned up and an error is logged to the console.

属性

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 🔗

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


方法说明

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

Converts a native engine type to a JSON-compliant value.

By default, objects are ignored for security reasons, unless full_objects is true.

You can convert a native value to a JSON string like this:

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_lineget_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_precisiontrue,则在字符串化浮点数时,除可靠数字外,还将对不可靠数字进行字符串化,以保证准确解码。

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 🔗

Converts a JSON-compliant value that was created with from_native back to native engine types.

By default, objects are ignored for security reasons, unless allow_objects is true.

You can convert a JSON string back to a native value like this:

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