Serialization

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

Blockly propose deux formats pour ces données: JSON et XML. Nous vous recommandons d'utiliser le système JSON pour les nouveaux projets et d'effectuer la mise à niveau des anciens projets utilisant XML. Le système XML est l'ancien format d'enregistrement. Il ne sera pas supprimé, mais aucune nouvelle fonctionnalité ne lui sera ajoutée.

Système JSON

Remarque :Pour savoir comment passer au format JSON à partir du format 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 chargé de sérialiser et de désérialiser 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 de l'ensemble d'un espace de travail 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 (par exemple, des blocs, des variables, des 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 possède un ordre de désérialisation explicite, ce qui permet d'éviter plus facilement la duplication d'état lors d'un enregistrement.

Lorsque Blockly.serialization.workspaces.load est appelé, les sérialiseurs reçoivent un état à désérialiser par ordre de priorité. Cela est expliqué plus en détail dans la section Sérialiseurs. 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 de 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 de niveau supérieur individuels sont désérialisés dans un ordre arbitraire.
   1. Le type est désérialisé. Cela construit le bloc, déclenche sa méthode d'initialisation et mélange les extensions.
   2. Les attributs sont désérialisés. Cela inclut les propriétés pouvant s'appliquer à n'importe quel bloc. (par exemple, "x", "y", "collapsed", "disabled" et "data").
   3. L'état supplémentaire est désérialisé. Pour en savoir plus, consultez la documentation sur les extensions et mutateurs.
   4. Le bloc est associé à son parent (s'il existe).
   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 un ordre 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 l'ordre dépend d'un élément inférieur dans l'ordre, 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 son état ne soit désérialisé.

Toutefois, si une entrée n'existe que si un champ possède une valeur donnée, 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é. Ensuite, vous pourrez ajouter l'entrée à votre bloc. En règle générale, l'ajout de l'entrée est déclenché par un outil de validation.

Notez que la règle concernant la duplication d'état doit également prendre en compte 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.

Hooks de blocage

Pour savoir comment ajouter une sérialisation supplémentaire aux blocs, consultez la documentation sur les extensions et les modificateurs.

Crochets 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 s'occupent de la sérialisation des informations sur les blocs et les variables, mais si vous souhaitez sérialiser d'autres informations, vous devrez 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.
• Fonction permettant de save l'état du plug-in/système associé au sérialiseur.
• Fonction permettant de clear l'état.
• Fonction permettant de load l'état.

• Un priority, utilisé pour 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 des valeurs de priorité plus positives sont déclenchés avant les sérialiseurs ayant des valeurs de priorité moins positives.

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

1. La fonction clear fournie est appelée. Cela garantit que l'état de votre plug-in/système est propre avant qu'un autre état ne soit chargé. Par exemple, le sérialiseur de commentaires de l'espace de travail supprimerait 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 dans un nœud XML. Il s'agissait du système de sérialisation d'origine de Blockly. Il a été mis en veille, ce qui signifie qu'il ne recevra plus de nouvelles fonctionnalités. Par conséquent, nous vous recommandons d'utiliser le système JSON dans la mesure du possible.

Remarque :Pour savoir comment migrer vers le format 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

Pour savoir comment ajouter une sérialisation supplémentaire aux blocs, consultez la documentation sur les extensions et les modificateurs.

Crochets de champ

Pour savoir comment sérialiser 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 le XML. Le système JSON vous permet de sérialiser l'état de votre espace de travail dans un objet JavaScript. Cette approche présente des avantages pour les raisons suivantes:

1. Le format JSON est facile à compresser ou à convertir dans un autre format.
2. Le format JSON est facile à utiliser de manière programmatique.
3. Il est facile d'étendre et d'ajouter des données au format JSON.

De plus, le système XML ne reçoit plus de mises à jour et manque déjà de 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 savoir comment effectuer la mise à niveau.