Serialisierung

Bei der Serialisierung wird der Status des Arbeitsbereichs gespeichert, damit er später wieder in den Arbeitsbereich geladen werden kann. Dazu gehört das Serialisieren 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 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 zu aktualisieren. Das XML-System ist das alte Speicherformat. Sie wird nicht entfernt, erhält aber keine neuen Funktionen.

JSON-System

Hinweis: Informationen zur Migration von XML zu JSON finden Sie in der Migrationsanleitung.

Das JSON-Serialisierungssystem besteht aus mehreren Serialisierern. 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 Status eines bestimmten Plug-ins oder Systems verantwortlich.

Speichern und Laden

Arbeitsbereiche

Sie können den Status eines gesamten Arbeitsbereichs serialisieren oder deserialisieren. Rufen Sie dazu die Methoden save und load für den Namespace workspaces auf.

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

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

Einzelne Blöcke

Sie können einzelne Blöcke serialisieren oder deserialisieren, indem Sie die Methoden save und append für den 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 usw.) serialisieren 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, sodass eine Duplizierung des Status beim Speichern leichter verhindert werden kann.

Wenn Blockly.serialization.workspaces.load aufgerufen wird, erhalten die Serialisierer den Status, dass sie in der Reihenfolge Priorität deserialisieren müssen. Dies wird im Abschnitt Serializer näher erläutert. Der Zweck besteht darin, Serialisierer die Abhängigkeit vom Status anderer Systeme zu ermöglichen.

Die Reihenfolge für die Deserialisierung integrierter Serializer lautet:

1. Variablen sind deserialisiert.
2. Blöcke sind deserialisiert. Einzelne Stacks/Blöcke der obersten Ebene werden in einer beliebigen Reihenfolge deserialisiert.
   1. Der Typ ist deserialisiert. Dies löst die Init-Methode des Blocks, Einmischungen in Erweiterungen usw. aus.
   2. Attribute sind deserialisiert. Dazu gehören auch Properties, die für jeden Block gelten können. Beispiele: x, y, minimiert, deaktiviert, Daten usw.
   3. Der zusätzliche Status ist deserialisiert. Weitere Informationen finden Sie in der Dokumentation zu Erweiterungen und Mutatoren.
   4. Der Block ist mit dem übergeordneten Element (falls vorhanden) verbunden.
   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 auch 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 soll

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 beispielsweise ein Feld 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 keine Informationen über das Feld zu Ihrem zusätzlichen Status hinzufügen. Das liegt daran, dass der Status des Felds zuerst deserialisiert wird. Wenn dies der Fall ist, können Sie die Eingabe dem Block hinzufügen. In der Regel wird das Hinzufügen der Eingabe durch einen validator ausgelöst.

In der Regel zum Duplizieren von Status sollte außerdem berücksichtigt werden, 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 über A hinzufügen, falls B vor A deserialisiert wird.

Blockhaken

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 Serializer 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 vom JSON-System beispielsweise nicht standardmäßig serialisiert. Für die Serialisierung müssen Sie einen zusätzlichen Serializer registrieren.

Zusätzliche Serialisierer werden häufig verwendet, um den Status 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 mehrere Angaben machen:

• Ein Name für den Serialisierer, unter dem die Daten auch gespeichert werden.
• 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 Ihres 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 in der Reihenfolge der Priorität ausgelöst. Serialisierer mit positiveren Prioritätswerten werden vor Serialisierern mit weniger positiven Prioritätswerten ausgelöst.

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

1. Die bereitgestellte clear-Funktion wird aufgerufen. Dadurch wird sichergestellt, dass der Status Ihres Plug-ins/Systems bereinigt ist, bevor weitere Status geladen werden. Der Serialisierer „workspace-comments“ würde alle vorhandenen Kommentare aus dem Arbeitsbereich entfernen.
2. Die bereitgestellte load-Funktion wird aufgerufen.

XML-System

Mit dem XML-System können Sie Ihren Arbeitsbereich auf einen XML-Knoten serialisieren. Dies war das ursprüngliche Serialisierungssystem von Blockly. Sie hat nun einen Icebox-Effekt, was bedeutet, dass sie keine neuen Funktionen erhält. Daher empfehlen wir, nach Möglichkeit das JSON-System zu verwenden.

Hinweis: Informationen zur Migration zu JSON finden Sie in der Migrationsanleitung.

APIs

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

Blockhaken

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 mit einem JavaScript-Objekt serialisieren. Dies ist aus folgenden Gründen vorteilhaft:

1. JSON lässt sich leicht komprimieren oder in ein anderes Format konvertieren.
2. Die programmatische Arbeit mit JSON ist einfach.
3. JSON lässt sich einfach erweitern und Daten anhängen.

Darüber hinaus erhält das XML-System keine Updates mehr und es fehlen bereits Funktionen im Vergleich zum JSON-Serialisierer. 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.