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 数据的辅助类。

描述

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 🔗

• void set_data(value: Variant)

• Variant get_data()

包含解析到的 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_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 🔗

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)