Framework de lecteurs et d'éditeurs JSON

De RAD Studio
Aller à : navigation, rechercher

Remonter à JSON


Le framework de lecteurs et d'éditeurs JSON fournit des classes et des méthodes permettant de lire et d'écrire des données JSON dans un flux.

Remarque : RAD Studio a deux frameworks pour gérer les données JSON. Vous trouverez davantage de détails sur ces deux frameworks dans JSON.

Avec le framework de lecteurs et d'éditeurs JSON, vous pouvez effectuer les actions suivantes :

  • Ecriture de JSON : vous pouvez utiliser la classe TJSONObjectBuilder pour créer un objet JSON. La classe TJSONObjectBuilder est une enveloppe de la classe TJsonWriter qui fournit la logique permettant la sérialisation de données JSON.
Même si vous pouvez écrire des objets JSON en utilisant les classes TJSONObjectBuilder ou TJsonWriter, nous vous recommandons d'utiliser la classe TJSONObjectBuilder, car elle fournit une interface fluent (EN) pour écrire des objets JSON.
Voir Ecriture d'objets JSON pour davantage de détails.
  • Lecture de JSON : vous pouvez utiliser la classe TJSONIterator afin de parcourir les données JSON. La classe TJSONIterator est une enveloppe de la classe TJsonReader qui vous permet de lire des données sérialisées au format JSON.
Même si vous pouvez lire des données JSON en utilisant les classes TJSONIterator ou TJsonReader , nous vous recommandons d'utiliser la classe TJSONIterator, car elle fournit des fonctionnalités supplémentaires pour vous déplacer dans les données JSON.
Voir Lecture d'objets JSON pour plus de détails.
  • Lecture et écriture de données BSON : ce framework vous permet de lire et d'écrire des données BSON au moyen des classes TBsonReader et TBsonWriter.
Pour plus de détails, voir BSON.

Ecriture d'objets JSON

Utilisez le framework System.JSON.Builders afin d'écrire des objets JSON. Vous devez créer une instance de TJSONObjectBuilder et appeler la méthode BeginObject afin de démarrer l'objet JSON. La méthode TJSONObjectBuilder.BeginObject renvoie un TJSONCollectionBuilder.TPairs pour le chaînage de méthodes (EN).

Le chaînage de méthode pour l'écriture de JSON inclut les classes suivantes :

  • TJSONCollectionBuilder.TPairs : utilisée pour ajouter des paires clés-valeur à un objet JSON.
  • TJSONCollectionBuilder.TElements : utilisée pour ajouter des éléments à un tableau JSON.
  • TJSONCollectionBuilder.TParentCollection : utilisée pour ajouter des paires clé-valeur à un objet JSON, ainsi que pour ajouter des éléments à un tableau JSON. La classe TParentCollection représente la structure du parent ; cette classe est renvoyée dans des méthodes telles que EndObject et EndArray, parce que le parent pourrait être un objet JSON ou un tableau JSON.

Vous n'avez pas besoin de créer d'instances des classes ci-dessus, car les instances requises sont renvoyées lors du chaînage de méthodes au moment où vous appelez les méthodes.

Ajout d'objets JSON

Utilisez la méthode BeginObject pour démarrer un objet.

Appelez Add pour ajouter une paire clé-valeur à l'objet JSON.

Appelez AddPairs pour ajouter plusieurs paires clé-valeur à l'objet JSON.

Vous pouvez aussi appeler :

  • AddNull pour ajouter une clé ayant la valeur null.
  • AddUndefined pour ajouter une clé ayant la valeur undefined.
  • AddMinKey pour ajouter une clé ayant la valeur MinKey.
  • AddMaxKey pour ajouter une clé ayant la valeur MaxKey.

Appelez la méthode EndObject pour terminer l'objet.

Ajout de tableaux JSON

Utilisez la méthode BeginArray pour démarrer un tableau.

Appelez Add pour ajouter une valeur au tableau JSON.

Appelez AddElements pour ajouter plusieurs valeurs à un tableau JSON.

Vous pouvez aussi appeler :

  • AddNull pour ajouter une valeur null.
  • AddUndefined pour ajouter une valeur undefined.
  • AddMinKey pour ajouter une valeur MinKey.
  • AddMaxKey pour ajouter une valeur MaxKey.

Appelez la méthode EndArray pour terminer le tableau.

Terminaison d'objets et de tableaux JSON

Vous pouvez appeler EndObject et EndArray pour terminer, respectivement, des objets et des tableaux. Vous pouvez également appeler EndAll afin de terminer la structure tout entière d'un seul coup.

Lecture d'objets JSON

Utilisez le framework System.JSON.Builders pour lire des objets JSON.

Vous devez créer une instance de TJSONIterator indiquant le lecteur JSON contenant les données JSON.

Utilisez la méthode Next pour aller au premier élément du JSON. Continuez d'appeler Next pour aller aux éléments suivants du niveau JSON en cours.

Pour vous déplacer directement sur une valeur, un objet ou un tableau particulier, vous pouvez appeler la méthode Next en transmettant le nom de l'élément sur lequel vous voulez vous déplacer. Cet élément doit se situer dans la même structure de niveau JSON que l'itérateur. Si l'itérateur est un tableau, vous pouvez appeler Next en transmettant l'index du tableau sous forme de chaîne afin de vous déplacer directement sur cet élément tableau. Utilisez Index afin d'obtenir l'index en cours du tableau que vous lisez. Index renvoie -1 quand vous ne lisez pas un tableau.

Vous pouvez utiliser la méthode Rewind pour déplacer l'itérateur au début des données JSON.

Pour trouver un élément particulier, utilisez la méthode Find et indiquez le chemin d'accès de l'élément que vous voulez trouver. Cette méthode renvoie True si l'élément a été trouvé et déplace l'itérateur sur l'élément en question. Vous pouvez utiliser cette méthode pour vous déplacer entre différents niveaux de JSON. Vous devez indiquer le chemin d'accès complet à l'élément en utilisant une notation à points, par exemple : 'entities.urls[0].indices[1]'.

Remarque : Les méthodes Rewind et Find déclenchent une exception si vous ne transmettez pas de procédure de rembobinage à la création de l'itérateur.

Déplacement entre les niveaux de JSON

  • Entrée dans un tableau ou une structure d'objets
Le déplacement dans le JSON avec Next consiste en un déplacement dans le niveau en cours du JSON. Pour entrer dans un tableau ou un objet, appelez Recurse avant de déplacer l'itérateur sur un token JSON avec les types StartArray ou StartObject, et appelez à nouveau Recurse juste après l'appel de Next pour vous déplacer sur le token StartArray ou StartObject afin d'entrer dans ce tableau ou cet objet.
  • Sortie d'un tableau ou d'une structure d'objets
Quand vous êtes prêt à sortir d'une structure et à vous déplacer au niveau parent, utilisez Return. Cette méthode ignore le contenu restant du tableau ou de l'objet, s'il en existe un, et revient au tableau ou objet parent.
  • Utilisez Depth pour connaître la profondeur du niveau auquel l'itérateur se trouve actuellement.

Lecture d'éléments JSON

  • Lecture de clés
Utilisez Key pour lire le nom de l'élément en cours. Key indique le nom de l'élément que l'itérateur lit actuellement, qu'il s'agisse du nom d'un objet, de celui d'un tableau, de l'index d'un tableau, ou du nom d'une clé dans le cas de paires clé-valeur.
  • Lecture de valeurs
Pour lire une valeur, vous devez connaître son Type, car vous avez besoin d'utiliser la propriété appropriée en fonction du type. Par exemple, pour accéder à la valeur d'un élément de type chaîne, vous devez utiliser la propriété AsString.
Pour plus de détails sur les propriétés à utiliser en fonction du type de valeur que vous lisez, voir le tableau des propriétés de valeur.

Voir aussi

Exemples de code