Serialisierung

Durch die Serialisierung wird der Status des Arbeitsbereichs gespeichert, damit er später wieder in den Arbeitsbereich geladen werden kann. Dazu gehört auch die Serialisierung des Status aller Blöcke, Variablen oder Plug-ins, die Sie speichern möchten. Sie können alle zu speichernden Daten zur einfachen Speicherung in ein textbasiertes Format konvertieren und diese Daten 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 für ältere Projekte XML zu verwenden, um Upgrades durchzuführen. Das XML-System ist das alte Speicherformat. Die App wird nicht entfernt, es werden ihr aber keine neuen Funktionen mehr hinzugefügt.

JSON-System

Hinweis: Informationen zur Migration von XML zu JSON finden Sie im Migrationsleitfaden.

Das JSON-Serialisierungssystem besteht aus mehreren Serializern. Es gibt integrierte Serializer für Blöcke und Variablen. Sie können auch zusätzliche Serializer registrieren. Jeder Serializer 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 serialisieren oder deserialisieren, indem Sie die Methoden save und load für den Namespace workspaces aufrufen.

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

Bei diesen Aufrufen werden alle einzelnen Systeme (die durch Serializer dargestellt werden) serialisiert oder deserialisiert, die im Arbeitsbereich registriert sind.

Einzelne Blöcke

Sie können einzelne Blöcke serialisieren oder deserialisieren, indem Sie die Methoden save und append im Namespace blocks aufrufen.

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) serialisieren oder deserialisieren, indem Sie den zugehörigen Serializer erstellen und seine 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, die es einfacher macht, das Duplizieren des Status innerhalb einer Speicherung zu verhindern.

Wenn Blockly.serialization.workspaces.load aufgerufen wird, erhalten die Serializer den Status, der in der Reihenfolge der Priorität deserialisiert werden soll. Dies wird im Abschnitt Serializer näher erläutert. Der Zweck besteht darin, dass Serializer vom Status anderer Systeme abhängen können.

Die Reihenfolge der Deserialisierung integrierter Serializer ist:

1. Variable Modelle werden deserialisiert.
2. Vorgangsmodelle werden deserialisiert.
3. Blöcke werden deserialisiert. Einzelne Blöcke der obersten Ebene werden in beliebiger Reihenfolge deserialisiert.
   1. Der Typ wird deserialisiert. Dadurch wird der Block erstellt, seine Init-Methode ausgelöst und Erweiterungen werden eingefügt.
   2. Attribute werden deserialisiert. Dazu gehören auch Properties, die auf jeden Block angewendet werden können. Beispiele: x, y, minimiert, deaktiviert und Daten.
   3. Zusätzlicher Status wird deserialisiert. Weitere Informationen finden Sie in der Dokumentation zu Erweiterungen und Mutatoren.
   4. Der Block ist mit seinem übergeordneten Element verbunden (falls vorhanden).
   5. Symbole werden deserialisiert. Einzelne Symbole werden in einer beliebigen Reihenfolge deserialisiert.
   6. Felder werden deserialisiert. Einzelne Felder werden in einer beliebigen Reihenfolge deserialisiert.
   7. Eingabeblöcke werden deserialisiert. Dazu gehören Blöcke, die mit Wert- und Anweisungseingaben verbunden sind. Einzelne Eingaben werden in beliebiger Reihenfolge deserialisiert.
   8. Die nächsten Blöcke werden deserialisiert.

Wann werden zusätzliche Status gespeichert?

Wenn bei Blöcken ein Element in der Reihenfolge von einem Element in einer höheren Position abhängt, sollten Sie diese Daten duplizieren und dem 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 Zustand hinzufügen, damit das Feld Ihrem Block hinzugefügt werden kann, bevor der Status des Felds deserialisiert wird.

Wenn eine Eingabe jedoch nur vorhanden ist, wenn ein Feld einen bestimmten Wert hat, müssen Sie Ihrem zusätzlichen Status keine Informationen zum Feld hinzufügen. Das liegt daran, dass der Status Ihres Felds zuerst deserialisiert wird. Danach können Sie die Eingabe in den Block einfügen. Normalerweise wird das Hinzufügen der Eingabe durch einen Validator ausgelöst.

Beachten Sie, dass bei der Regel zum Duplizieren des Status auch berücksichtigt werden muss, dass Blockstacks, 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 Ihrem zusätzlichen Status Informationen zu A hinzufügen, falls B vor A deserialisiert wird.

Block-Hooks

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

Feld-Hooks

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

Serializer-Hooks

Mit dem JSON-System können Sie Serializer registrieren, die einen bestimmten Status serialisieren und deserialisieren. Die integrierten Serializer von Blockly kümmern sich um die Serialisierung von Informationen zu Blöcken und Variablen. Wenn Sie jedoch andere Informationen serialisieren möchten, müssen Sie einen eigenen Serializer hinzufügen. Kommentare auf Workspace-Ebene werden beispielsweise standardmäßig nicht vom JSON-System serialisiert. Wenn Sie sie serialisieren möchten, müssen Sie einen zusätzlichen Serializer registrieren.

Zusätzliche Serializer werden häufig verwendet, um den Zustand eines Plug-ins zu serialisieren und zu deserialisieren.

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 Serializer registrieren, müssen Sie Folgendes angeben:

• Ein Name für den Serializer, unter dem die Daten gespeichert werden.
• Eine Funktion, um den Status des mit dem Serializer verknüpften Plug-ins/Systems save zu prüfen.
• Eine Funktion, um den Status clear zu setzen.
• Eine Funktion, um den Status load zu setzen.

• Eine priority, mit der die Deserialisierungsreihenfolge bestimmt wird.

  Sie können die Priorität Ihres Serializers auf den vordefinierten Prioritäten basieren.

Wenn Blockly.serialization.workspaces.save aufgerufen wird, wird die save-Funktion jedes Serializers aufgerufen und die 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 in der Reihenfolge der Priorität ausgelöst. Serializer mit höheren Prioritätswerten werden vor Serializern mit niedrigeren Prioritätswerten ausgelöst.

Wenn ein Serializer ausgelöst wird, geschieht Folgendes:

1. Die angegebene clear-Funktion wird aufgerufen. So wird sichergestellt, dass der Zustand Ihres Plug-ins/Systems sauber ist, bevor weitere Statusinformationen geladen werden. Der Workspace-Kommentar-Serializer würde beispielsweise 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 zu einem XML-Knoten serialisieren. Dies war das ursprüngliche Serialization-System von Blockly. Es wurde jetzt eingefroren, was bedeutet, dass es keine neuen Funktionen mehr erhält. Daher empfehlen wir, wenn möglich das JSON-System zu verwenden.

Hinweis: Informationen zur Migration zu JSON finden Sie im Migrationsleitfaden.

APIs

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

Block-Hooks

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

Feld-Hooks

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

Zwischen JSON und XML wählen

Wir empfehlen den JSON-Serializer gegenüber XML. Mit dem JSON-System können Sie den Status Ihres Arbeitsbereichs in ein JavaScript-Objekt serialisieren. Das hat folgende Vorteile:

1. JSON-Dateien lassen sich leicht komprimieren oder in ein anderes Format konvertieren.
2. JSON lässt sich einfach programmatisch verarbeiten.
3. JSON lässt sich leicht erweitern und Daten können angefügt werden.

Außerdem wird das XML-System nicht mehr aktualisiert und es fehlen ihm bereits Funktionen im Vergleich zum JSON-Serializer. Sie können beispielsweise Ihren eigenen JSON-Serializer registrieren, um zusätzliche Daten wie Daten für von Ihnen hinzugefügte Plug-ins oder Anpassungen ganz einfach zu speichern und zu laden. Das ist im XML-System nicht möglich.

Wenn Sie bisher die XML-Serialisierung verwendet haben, finden Sie im Migrationsleitfaden Informationen zum Upgrade.