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

Hérite de : Resource < RefCounted < Object

Classe d'aide pour créer et interpréter des données JSON.

Description

La classe JSON permet à tous les types de données d'être convertis en et d'une chaîne JSON. Ceci est utile pour la sérialisation de données, par exemple pour enregistrer dans un fichier ou envoyer sur le réseau.

stringify() est utilisée pour convertir tout type de données en une chaîne JSON.

parse() est utilisée pour convertir des données JSON existantes en un Variant qui peut être utilisé dans Godot. Si parsé avec succès, utilisez data pour récupérer le Variant et utilisez @GlobalScope.typeof() pour vérifier si le type du Variant est celui que vous attendez. Les objets JSON sont convertis en un Dictionary, mais les données JSON peuvent être utilisées pour stocker des Arrays, des nombres, des Strings et même seulement un booléen.

var donnees_a_envoyer = ["a", "b", "c"]
var chaine_json = JSON.stringify(donnees_a_envoyer)
# Sauvegarder les données
# ...
# Récupérer les données
var json = JSON.new()
var erreur = json.parse(chaine_json)
if erreur == OK:
    var donnees_recues = json.data
    if typeof(donnees_recues) == TYPE_ARRAY:
        print(donnees_recues) # Affiche le tableau.
    else:
        print("Données inattendues")
else:
    print("Erreur du parsing JSON : ", json.get_error_message(), " dans ", json_string, " à la ligne ", json.get_error_line())

Alternativement, vous pouvez parser des chaînes en utilisant la méthode statique parse_string(), mais il ne gère pas les erreurs.

var donnes = JSON.parse_string(chaine_json) # Renvoie null si le parsing a echoué.

Note : Les deux méthodes de parsing ne sont pas entièrement conformes à la spécification JSON :

Les virgules de fin dans les tableaux ou les objets sont ignorées, au lieu de causer une erreur de parsing.
Les caractères de nouvelle ligne et de tabulations sont acceptés en caractères alphabétiques et sont traités comme leurs séquences d'échappement correspondantes \n et \t.
Les chiffres sont parsés en utilisant String.to_float() qui est généralement plus laxiste que la spécification JSON.
Certaines erreurs, telles que les séquences Unicode invalides, ne provoquent pas d'erreur de parsing. Au lieu de cela, la chaîne est nettoyée et une erreur est affichée dans la console.

Propriétés

Variant

data

null

Méthodes

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

Descriptions des propriétés

Variant data = null 🔗

void set_data(value: Variant)
Variant get_data()

Contient les données JSON parsées en leur forme de Variant.

Descriptions des méthodes

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

Convertit un type natif du moteur en une valeur compatible JSON.

Par défaut, les objets sont ignorés pour des raisons de sécurité, sauf si full_objects vauttrue.

Vous pouvez convertir une valeur native en une chaîne JSON comme ceci :

func encoder_donnees(valeur, objets_complets = false):
    return JSON.stringify(JSON.from_native(valeur, objets_complets))

int get_error_line() const 🔗

Renvoie 0 si le dernier appel à parse() était un succès, ou le numéro de ligne où le parsing a échoué.

String get_error_message() const 🔗

Renvoie une chaîne vide si le dernier appel à parse() était un succès, ou le message d'erreur si il a échoué.

String get_parsed_text() const 🔗

Renvoie le texte parsé par parse() (nécessite de passer keep_text à parse()).

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

Essaye de parser le texte json_text fourni.

Renvoie une erreur Error. Si le parsing était un succès, elle renvoie @GlobalScope.OK et le résultat peut être récupéré en utilisant data. Si c'était un échec, utilisez get_error_line() et get_error_message() pour identifier la source de l'échec.

Variante non statique de parse_string(), si vous voulez gérer les erreurs de manière personnalisée.

L'argument optionnel keep_text ordonne au parseur de conserver une copie du texte original. Ce texte peut être obtenu plus tard en utilisant la fonction get_parsed_text() et est utilisé lors de la sauvegarde de la ressource (au lieu de générer un nouveau texte à partir de data).

Variant parse_string(json_string: String) static 🔗

Essaie de parser le json_string fourni et renvoie les données parsées. Renvoie null si le parsing a échoué.

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

Convertit une variable Variant en texte JSON et renvoie le résultat. Utile pour sérialiser les données pour les enregistrer ou les envoyer à travers le réseau.

Note : Les spécifications du JSON ne définissent pas de types entier ou flottant, et ne définissent que le type commun number. Donc, convertir un Variant en JSON transformera tous les nombres en type float.

Note : Si full_precision vaut true, lors de la conversion des flottants, les chiffres non fiables sont convertis avec les chiffres fiables pour garantir un décodage exact.

La paramètre indent contrôle si et comment le JSON doit être indenté, la chaine de caractères utilisé pour ce paramètre sera utilisé pour l'indentation de la sortie, et même les espaces " " fonctionneront. \t et \n peuvent aussi être utilisé pour la tabulation, ou pour le retour à la ligne, respectivement.

Avertissement : Les nombres non-finis ne sont pas gérés par JSON. Toute occurrences de @GDScript.INF sera remplacée par 1e99999, et négatif @GDScript.INF sera remplacé par -1e99999, mais ils pourront être interprétés correctement par la plupart des analyseurs JSON. @GDScript.NAN sera remplacé par null, et ne sera pas interprété en NaN par les analyseurs JSON. Si vous attendez des nombres non-finis, considérez de passer vos données par from_native() avant toute opération.

Exemples de sortie :

## JSON.print(my_dictionary)
{"name" :"mon_dictionnaire","version" :"1.0.0","entities" :[{"name" :"élément_0","value" :"valeur_0"},{"name" :"élément_1","value" :"valeur_1"}]}

## JSON.print(my_dictionary, "\t")
{
    "name" : "mon_dictionnaire",
    "version" : "1.0.0",
    "entities" : [
        {
            "name" : "élément_0",
            "value" : "valeur_0"
        },
        {
            "name" : "élément_1",
            "value" : "valeur_1"
        }
    ]
}

## JSON.print(my_dictionary, "...")
{
..."name" : "mon_dictionnaire",
..."version" : "1.0.0",
..."entities" : [
......{
........."name" : "élément_0",
........."value" : "valeur_0"
......},
......{
........."name" : "élément_1",
........."value" : "valeur_1"
......}
...]
}

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

Convertit une valeur compatible-JSON qui a été créée avec from_native() vers un type natif du moteur.

Par défaut, les objets sont ignorés pour des raisons de sécurité, sauf si allow_objects vaut true.

Vous pouvez convertir une chaîne JSON en une valeur native comme ceci :

func decoder_donnees(chaine, autoriser_objets = false):
    return JSON.to_native(JSON.parse_string(chaine), autoriser_objets)