Serialisierung

Bei der Serialisierung wird der Status des Arbeitsbereichs gespeichert, damit er später wieder in den Arbeitsbereich geladen werden kann. Dazu gehört auch das Serialisieren des Status aller Blöcke, Variablen oder Plug-ins, die Sie speichern möchten. Sie können alle zu speichernden Daten in ein textbasiertes Format konvertieren, um sie einfach zu speichern, und diese Daten dann später wieder in einen voll funktionsfähigen Arbeitsbereich laden.

Blockly bietet zwei Formate für diese Daten: JSON und XML. Wir empfehlen, für neue Projekte das JSON-System zu verwenden und ältere Projekte mit XML für Upgrades zu empfehlen. Das XML-System ist das alte Speicherformat. Es wird nicht entfernt, erhält aber keine neuen Funktionen.

JSON-System

Das JSON-Serialisierungssystem besteht aus mehreren Serializern. Es gibt integrierte Serialisierer für Blöcke und Variablen und Sie können auch zusätzliche Serialisierer registrieren. Jeder Serialisierer ist für die Serialisierung und Deserialisierung des Zustands eines bestimmten Plug-ins oder Systems verantwortlich.

Speichern und Laden

Arbeitsbereiche

Sie können den Status eines gesamten Arbeitsbereichs seriell oder deserialisieren, indem Sie die Methoden save und load im Namespace workspaces aufrufen.

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

Mit diesen Aufrufen werden alle einzelnen Systeme (dargestellt durch Serialisierer), die im Arbeitsbereich registriert sind, seriell oder deserialisiert.

Einzelne Bausteine

Sie können einzelne Blöcke serialisieren oder deserialisieren. Rufen Sie dazu die Methoden save und append im Namespace blocks auf.

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

Einzelne Systeme

Sie können einzelne Systeme (z.B. Blöcke, Variablen, Plug-ins) seriell oder deserialisieren, indem Sie den zugehörigen Serializer erstellen und die Methoden save und load aufrufen.

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

Deserialisierungsreihenfolge

Das JSON-System hat eine explizite Deserialisierungsreihenfolge, wodurch eine Duplizierung des Status beim Speichern leichter verhindert werden kann.

Wenn Blockly.serialization.workspaces.load aufgerufen wird, erhalten die Serialisierer den Status, der in der Reihenfolge der Priorität deserialisiert werden muss. Dies wird im Abschnitt Serializer näher erläutert. Der Zweck besteht darin, Serialisierer vom Status anderer Systeme abhängig zu machen.

Die Deserialisierung integrierter Serializer sieht so aus:

  1. Variablenmodelle sind deserialisiert.
  2. Prozedurmodelle sind deserialisiert.
  3. Blöcke werden deserialisiert. Einzelne Blöcke der obersten Ebene werden in einer beliebigen Reihenfolge deserialisiert.
    1. Der Typ ist deserialisiert. Dadurch wird der Block erstellt, seine Init-Methode ausgelöst und Erweiterungen hinzugefügt.
    2. Attribute sind deserialisiert. Dazu gehören auch Properties, die für jeden Block gelten können. Beispiel: x, y, minimiert, deaktiviert und Daten.
    3. Der zusätzliche Zustand ist deserialisiert. Weitere Informationen finden Sie in der Dokumentation zu Erweiterungen und Mutatoren.
    4. Der Block ist mit dem übergeordneten Element verbunden (falls vorhanden).
    5. Symbole sind deserialisiert. Einzelne Symbole werden in einer beliebigen Reihenfolge deserialisiert.
    6. Felder sind deserialisiert. Einzelne Felder werden in einer beliebigen Reihenfolge deserialisiert.
    7. Eingabeblöcke sind deserialisiert. Dazu gehören Blöcke, die mit Wert- und Anweisungseingaben verbunden sind. Einzelne Eingaben werden in einer beliebigen Reihenfolge deserialisiert.
    8. Nächste Blöcke werden deserialisiert.

Wann zusätzlicher Status gespeichert werden sollte

Wenn Sie bei Blöcken eine niedrigere Reihenfolge haben, die von etwas höherem in der Reihenfolge abhängt, sollten Sie diese Daten duplizieren und zu Ihrem zusätzlichen Status hinzufügen.

Wenn Sie beispielsweise ein Feld haben, das nur vorhanden ist, wenn ein nächster Block verbunden ist, sollten Sie Informationen über diesen nächsten Block zu Ihrem zusätzlichen Status hinzufügen, damit das Feld dem Block hinzugefügt werden kann, bevor der Status des Felds deserialisiert wird.

Wenn Sie jedoch eine Eingabe haben, die nur vorhanden ist, wenn ein Feld einen bestimmten Wert hat, müssen Sie zu Ihrem zusätzlichen Status keine Informationen über das Feld hinzufügen. Das liegt daran, dass der Status des Felds zuerst deserialisiert wird. Wenn dies der Fall ist, können Sie die Eingabe zu Ihrem Block hinzufügen. In der Regel wird das Hinzufügen der Eingabe durch einen validator ausgelöst.

In der Regel zum Duplizieren des Status sollte außerdem berücksichtigt werden, dass Blockstapel, Symbole, Felder und Eingabeblöcke in einer beliebigen Reihenfolge deserialisiert werden. Wenn beispielsweise ein Feld B nur vorhanden ist, wenn ein anderes Feld A einen bestimmten Wert hat, sollten Sie Informationen über A zu Ihrem zusätzlichen Status hinzufügen, falls B vor A deserialisiert wird.

Block-Hooks

Informationen zum Hinzufügen einer zusätzlichen Serialisierung zu Blöcken finden Sie in der Dokumentation zu Erweiterungen und Mutators.

Field Hooks

Informationen zum Serialisieren von Feldern finden Sie in der Dokumentation zu benutzerdefinierten Feldern.

Serializer-Hooks

Mit dem JSON-System können Sie Serialisierer registrieren, die einen bestimmten Zustand serialisieren und deserialisieren. Die integrierten Serialisierer von Blockly kümmern sich um die Serialisierung von Informationen über Blöcke und Variablen. Wenn Sie jedoch andere Informationen serialisieren möchten, müssen Sie Ihren eigenen Serializer hinzufügen. Kommentare auf Arbeitsbereichsebene werden z. B. vom JSON-System nicht standardmäßig serialisiert. Für die Serialisierung müssen Sie einen zusätzlichen Serializer registrieren.

Zum Serialisieren und Deserialisieren des Status eines Plug-ins werden häufig zusätzliche Serializer verwendet.

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

Wenn Sie einen Serialisierer registrieren, müssen Sie mehrere Informationen angeben:

  • Ein Name für den Serialisierer, unter dem die Daten ebenfalls gespeichert sind.
  • Eine Funktion zum save des Status des Plug-ins/Systems, das dem Serializer zugeordnet ist.
  • Eine Funktion zum clear des Status
  • Eine Funktion zum load des Status

  • Ein priority, mit dem die Deserialisierungsreihenfolge festgelegt wird.

    Sie können die Priorität des Serializers auf den integrierten Prioritäten basieren.

Wenn Blockly.serialization.workspaces.save aufgerufen wird, wird die save-Funktion jedes Serializers aufgerufen und die zugehörigen Daten werden der endgültigen JSON-Ausgabe hinzugefügt:

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

Wenn Blockly.serialization.workspaces.load aufgerufen wird, wird jeder Serializer nach Priorität ausgelöst. Serializer mit mehr positiven Prioritätswerten werden vor Serializern mit weniger positiven Prioritätswerten ausgelöst.

Wenn ein Serializer ausgelöst wird, passieren zwei Dinge:

  1. Die angegebene clear-Funktion wird aufgerufen. Dadurch wird sichergestellt, dass der Status Ihres Plug-ins/Systems sauber ist, bevor ein weiterer Status geladen wird. Der Serializer „workspace-comments“ würde alle vorhandenen Kommentare aus dem Arbeitsbereich entfernen.
  2. Die angegebene load-Funktion wird aufgerufen.

XML-System

Mit dem XML-System können Sie Ihren Arbeitsbereich in einen XML-Knoten gruppieren. Dies war das ursprüngliche Serialisierungssystem von Blockly. Sie ist nun mit Iceboxes versehen und bietet daher keine neuen Funktionen. Daher empfehlen wir, nach Möglichkeit das JSON-System zu verwenden.

APIs

Informationen zu den APIs des XML-Systems finden Sie in der Referenzdokumentation.

Block-Hooks

Informationen zum Hinzufügen einer zusätzlichen Serialisierung zu Blöcken finden Sie in der Dokumentation zu Erweiterungen und Mutators.

Field Hooks

Informationen zum Serialisieren von Feldern finden Sie in der Dokumentation zu benutzerdefinierten Feldern.

Zwischen JSON und XML wählen

Wir empfehlen den JSON-Serialisierer über XML. Mit dem JSON-System können Sie den Status Ihres Arbeitsbereichs in ein JavaScript-Objekt serialisieren. Dies ist aus folgenden Gründen vorteilhaft:

  1. JSON lässt sich leicht komprimieren oder in ein anderes Format konvertieren.
  2. JSON lässt sich leicht programmatisch verwenden.
  3. JSON lässt sich einfach erweitern und an die Daten anhängen.

Darüber hinaus erhält das XML-System keine Updates mehr und es verfügt im Vergleich zum JSON-Serialisierer bereits über Funktionen. Sie können beispielsweise Ihren eigenen JSON-Serialisierer registrieren, um zusätzliche Daten einfach zu speichern und zu laden, z. B. Daten für Plug-ins oder von Ihnen hinzugefügte Anpassungen. Dies ist im XML-System nicht möglich.

Wenn Sie zuvor die XML-Serialisierung verwendet haben, finden Sie in der Migrationsanleitung Informationen zum Upgrade.