Serialization

La sérialisation enregistre l'état de votre espace de travail afin qu'il puisse y être chargé ultérieurement. Cela inclut la sérialisation de l'état des blocs, des variables ou des plug-ins que vous souhaitez enregistrer. Vous pouvez convertir toutes les données que vous devez enregistrer au format texte pour faciliter leur stockage, puis les charger ultérieurement dans un espace de travail entièrement fonctionnel.

Blockly fournit deux formats pour ces données: JSON et XML. Nous vous recommandons d'utiliser le système JSON pour les nouveaux projets et d'encourager la mise à niveau des projets plus anciens utilisant XML. Le système XML est l'ancien format de sauvegarde. Il ne sera pas supprimé, mais il ne recevra pas de nouvelles fonctionnalités.

Système JSON

Remarque :Pour en savoir plus sur la migration vers JSON à partir d'un fichier XML, consultez le guide de migration.

Le système de sérialisation JSON est composé de plusieurs sérialiseurs. Il existe des sérialiseurs intégrés pour les blocs et les variables, et vous pouvez également enregistrer des sérialiseurs supplémentaires. Chaque sérialiseur est responsable de la sérialisation et de la désérialisation de l'état d'un plug-in ou d'un système particulier.

Enregistrement et chargement

Espaces de travail

Vous pouvez sérialiser ou désérialiser l'état d'un espace de travail entier en appelant les méthodes save et load sur l'espace de noms workspaces.

const state = Blockly.serialization.workspaces.save(myWorkspace);
Blockly.serialization.workspaces.load(state, myWorkspace);

Ces appels sérialisent ou désérialisent tous les systèmes individuels (représentés par les sérialiseurs) enregistrés auprès de l'espace de travail.

Blocs individuels

Vous pouvez sérialiser ou désérialiser des blocs individuels en appelant les méthodes save et append sur l'espace de noms blocks.

const blockJson = Blockly.serialization.blocks.save(myBlock);
const duplicateBlock =
    Blockly.serialization.blocks.append(blockJson, myWorkspace);

Systèmes individuels

Vous pouvez sérialiser ou désérialiser des systèmes individuels (blocs, variables, plug-ins, etc.) en construisant le sérialiseur associé et en appelant ses méthodes save et load.

// Saves only the variables information for the workspace.
const serializer = new Blockly.serialization.variables.VariableSerializer();
const state = serializer.save(myWorkspace);
serializer.load(state, myWorkspace);

Ordre de désérialisation

Le système JSON présente un ordre de désérialisation explicite, ce qui permet d'éviter plus facilement la duplication de l'état dans un enregistrement.

Lorsque Blockly.serialization.workspaces.load est appelé, les sérialiseurs reçoivent l'état à désérialiser par ordre de priorité. Cette opération est expliquée plus en détail dans la section Sérialiseurs, et son objectif est de permettre aux sérialiseurs de dépendre de l'état d'autres systèmes.

L'ordre de désérialisation des sérialiseurs intégrés est le suivant:

1. Les modèles variables sont désérialisés.
2. Les modèles de procédure sont désérialisés.
3. Les blocs sont désérialisés. Les blocs individuels de premier niveau sont désérialisés dans un ordre arbitraire.
   1. Le type est désérialisé. Cette action construit le bloc, déclenche sa méthode d'initialisation et mélange des extensions.
   2. Les attributs sont désérialisés. Cela inclut les propriétés qui peuvent s'appliquer à n'importe quel bloc. Exemples: x, y, réduit, désactivé et données.
   3. L'état supplémentaire est désérialisé. Pour en savoir plus, consultez la documentation sur les extensions et les mutateurs.
   4. Le bloc est connecté à son parent (le cas échéant).
   5. Les icônes sont désérialisées. Les icônes individuelles sont désérialisées dans un ordre arbitraire.
   6. Les champs sont désérialisés. Les champs individuels sont désérialisés dans une commande arbitraire.
   7. Les blocs d'entrée sont désérialisés. Cela inclut les blocs connectés aux entrées de valeur et aux entrées d'instructions. Les entrées individuelles sont désérialisées dans un ordre arbitraire.
   8. Les blocs suivants sont désérialisés.

Quand enregistrer un état supplémentaire

Pour les blocs, si un élément de niveau inférieur dépend d'un élément de niveau supérieur, vous devez dupliquer ces données et les ajouter à votre état supplémentaire.

Par exemple, si un champ n'existe que si un bloc suivant est connecté, vous devez ajouter des informations sur ce bloc suivant à votre état supplémentaire, afin que le champ puisse être ajouté à votre bloc avant que l'état du champ ne soit désérialisé.

Toutefois, si une entrée n'existe que si un champ a une certaine valeur, vous n'avez pas besoin d'ajouter d'informations sur le champ à votre état supplémentaire. En effet, l'état de votre champ sera d'abord désérialisé, puis vous pourrez ajouter l'entrée à votre bloc. En général, l'ajout des entrées est déclenché par un validator.

Notez que la règle sur la duplication de l'état doit également tenir compte du fait que les piles de blocs, les icônes, les champs et les blocs d'entrée sont désérialisés dans un ordre arbitraire. Par exemple, si un champ B n'existe que si un autre champ A a une certaine valeur, vous devez ajouter des informations sur A à votre état supplémentaire au cas où B serait désérialisé avant A.

Crochets de blocs

Pour plus d'informations sur l'ajout d'une sérialisation supplémentaire aux blocs, consultez la documentation Extensions et mutations.

Hooks de champ

Pour en savoir plus sur la sérialisation des champs, consultez la documentation sur les champs personnalisés.

Hooks de sérialiseur

Le système JSON vous permet d'enregistrer des sérialiseurs qui sérialisent et désérialisent certains états. Les sérialiseurs intégrés de Blockly se chargent de sérialiser des informations sur les blocs et les variables, mais si vous souhaitez sérialiser d'autres informations, vous devez ajouter votre propre sérialiseur. Par exemple, les commentaires au niveau de l'espace de travail ne sont pas sérialisés par défaut par le système JSON. Si vous souhaitez les sérialiser, vous devez enregistrer un sérialiseur supplémentaire.

Des sérialiseurs supplémentaires sont souvent utilisés pour sérialiser et désérialiser l'état d'un plug-in.

Blockly.serialization.registry.register(
    'workspace-comments',  // Name
    {
      save: saveFn,      // Save function
      load: loadFn,      // Load function
      clear: clearFn,    // Clear function
      priority: 10,      // Priority
    });

Lorsque vous enregistrez un sérialiseur, vous devez fournir plusieurs éléments:

• Nom du sérialiseur, sous lequel les données sont également enregistrées.
• Une fonction permettant de save l'état du plug-in/système associé au sérialiseur.
• Une fonction pour clear l'état.
• Une fonction pour load l'état.

• Un élément priority, qui permet de déterminer l'ordre de désérialisation.

  Vous pouvez baser la priorité de votre sérialiseur sur les priorités intégrées

Lorsque Blockly.serialization.workspaces.save est appelé, la fonction save de chaque sérialiseur est appelée, et ses données sont ajoutées à la sortie JSON finale:

{
  "blocks": { ... },
  "workspaceComments": [ // Provided by workspace-comments serializer
    {
      "x": 239,
      "y": 31,
      "text": "Add 2 + 2"
    },
    // etc...
  ]
}

Lorsque Blockly.serialization.workspaces.load est appelé, chaque sérialiseur est déclenché par ordre de priorité. Les sérialiseurs ayant un plus grand nombre de valeurs de priorité positives sont déclenchés avant les sérialiseurs ayant moins de valeurs de priorité positives.

Lorsqu'un sérialiseur est déclenché, deux choses se produisent:

1. La fonction clear fournie est appelée. Cela garantit que l'état de votre plug-in/système est propre avant que d'autres états soient chargés. Par exemple, le sérialiseur de commentaires de l'espace de travail supprime tous les commentaires existants de l'espace de travail.
2. La fonction load fournie est appelée.

Système XML

Le système XML vous permet de sérialiser votre espace de travail en nœud XML. Il s'agissait du système de sérialisation original de Blockly. Il est maintenant placé dans une boîte glacée, ce qui signifie qu'il ne recevra pas de nouvelles fonctionnalités. Par conséquent, nous vous recommandons d'utiliser le système JSON si possible.

Remarque :Pour en savoir plus sur la migration vers JSON, consultez le guide de migration.

API

Pour en savoir plus sur les API du système XML, consultez la documentation de référence.

Crochets de blocs

Pour plus d'informations sur l'ajout d'une sérialisation supplémentaire aux blocs, consultez la documentation Extensions et mutations.

Hooks de champ

Pour en savoir plus sur la sérialisation des champs, consultez la documentation sur les champs personnalisés.

Choisir entre JSON et XML

Nous vous recommandons d'utiliser le sérialiseur JSON plutôt que XML. Le système JSON vous permet de sérialiser l'état de votre espace de travail dans un objet JavaScript. Cette approche est avantageuse pour les raisons suivantes:

1. JSON est facile à compresser ou à convertir dans un autre format.
2. Le format JSON est facile à utiliser de façon automatisée.
3. JSON est facile à étendre et à ajouter des données.

De plus, le système XML ne recevra plus de mises à jour et il lui manque déjà des fonctionnalités par rapport au sérialiseur JSON. Par exemple, vous pouvez enregistrer votre propre sérialiseur JSON pour enregistrer et charger facilement des données supplémentaires, telles que des données pour des plug-ins ou des personnalisations que vous avez ajoutées. Cela n'est pas possible dans le système XML.

Si vous avez déjà utilisé la sérialisation XML, consultez le guide de migration pour en savoir plus sur la mise à niveau.