Serializacja

Serializacja polega na zapisaniu stanu obszaru roboczego, aby można go było później załadować. Obejmuje to serializację stanu wszystkich bloków, zmiennych i wtyczek, które chcesz zapisywać. Możesz przekonwertować wszystkie dane, które chcesz zapisać, do formatu tekstowego, aby ułatwić ich przechowywanie, a potem załadować je z powrotem do w pełni funkcjonalnego obszaru roboczego.

Blockly udostępnia te dane w 2 formatach: JSON i XML. Zalecamy korzystanie z systemu JSON w przypadku nowych projektów, a w przypadku starszych projektów korzystających z XML – ich uaktualnianie. System XML to starszy format zapisu. Nie zostanie ona usunięta, ale nie będziemy dodawać do niej nowych funkcji.

System JSON

Uwaga: informacje o przechodzeniu z formatu XML na format JSON znajdziesz w przewodniku po migracji.

System serializacji JSON składa się z wielu serializatorów. Dostępne są wbudowane serializatory bloków i zmiennych. Możesz też zarejestrować dodatkowe serializatory. Każdy serializator odpowiada za serializację i deserializację stanu konkretnej wtyczki lub systemu.

Zapisywanie i wczytywanie

Obszary robocze

Stan całego obszaru roboczego możesz serializować i deserializować, wywołując metody save i load w przestrzeni nazw workspaces.

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

Te wywołania serializują lub deserializują wszystkie poszczególne systemy (reprezentowane przez serializatory), które są zarejestrowane w Workspace.

Poszczególne bloki

Możesz serializować i deserializować poszczególne bloki, wywołując metody save i append w przestrzeni nazw blocks.

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

Pojedyncze systemy

Możesz zserializować lub deserializować poszczególne systemy (np.bloki, zmienne, wtyczki itp.), tworząc powiązany serializator i wywołując jego metody save i 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);

Kolejność deserializacji

System JSON ma wyraźny porządek deserializacji, który ułatwia zapobieganie powielaniu stanu w zapisie.

Gdy wywoływana jest funkcja Blockly.serialization.workspaces.load, serializatory otrzymują stan do deserializacji w kolejności określonej przez priorytet. Więcej informacji na ten temat znajdziesz w sekcji Serwery serializujące. Ich zadaniem jest umożliwienie serwerom serializującym korzystania ze stanu z innych systemów.

Kolejność deserializacji wbudowanych serializatorów:

1. Modele zmienne podlegają deserializacji.
2. Modele procedur są deserializowane.
3. Bloczki są deserializowane. Poszczególne blokady najwyższego poziomu są deserializowane w dowolnej kolejności.
   1. Typ jest deserializowany. Ta metoda tworzy blok, uruchamia jego metodę init() i miesza w niej rozszerzenia.
   2. Atrybuty są deserializowane. Obejmuje to właściwości, które mogą dotyczyć dowolnego bloku. Na przykład: x, y, zwinięta, wyłączona i dane.
   3. Stan dodatkowy jest deserializowany. Więcej informacji znajdziesz w dokumentacji dotyczącej rozszerzeń i modyfikatorów.
   4. Blokada jest powiązana z blokadą rodzica (jeśli istnieje).
   5. Ikony są deserializowane. Poszczególne ikony są deserializowane w dowolnej kolejności.
   6. Pola są deserializowane. Poszczególne pola są deserializowane w dowolnej kolejności.
   7. Bloki wejściowe są deserializowane. Obejmuje to bloki połączone z danymi wejściowymi wartości i instrukcjami. Poszczególne dane wejściowe są deserializowane w dowolnej kolejności.
   8. Następujące bloki są deserializowane.

Kiedy zapisać dodatkowy stan

Jeśli w przypadku bloków masz coś niższego w kolejności, co zależy od czegoś wyższego w kolejności, zduplikuj te dane i dodaj je do dodatkowego stanu.

Jeśli na przykład masz pole, które istnieje tylko po połączeniu następnego bloku, należy dodać informacje o tym następnym bloku do dodatkowego stanu, tak aby można było dodać to pole do bloku, zanim jego stan zostanie deserializowany.

Jeśli jednak masz dane wejściowe, które występują tylko wtedy, gdy pole ma określoną wartość, nie musisz dodawać informacji o tym polu do dodatkowego stanu. Dzieje się tak, ponieważ stan pola zostanie najpierw zdeserializowany, a potem możesz dodać dane wejściowe do bloku. Zwykle dodanie danych wejściowych jest wywoływane przez walidator.

Pamiętaj, że reguła dotycząca powielania stanu powinna uwzględniać fakt, że grupy bloków, ikony, pola i bloki danych wejściowych są deserializowane w dowolnej kolejności. Jeśli na przykład masz pole B, które istnieje tylko wtedy, gdy inne pole A ma określoną wartość, powinieneś dodać informacje o polu A do dodatkowego stanu na wypadek, gdyby pole B zostało zdeserializowane przed polem A.

Blokowanie haków

Informacje o dodawaniu dodatkowej serializacji do bloków znajdziesz w dokumentacji dotyczącej rozszerzeń i modyfikatorów.

Haczyki w polu

Informacje o serii pól znajdziesz w dokumentacji dotyczącej pol niestandardowych.

Punkty zaczepienia serializatora

System JSON umożliwia rejestrowanie serializatorów, które serializują i deserializują stan. Wbudowane serializatory Blockly zajmują się serializacją informacji o blokach i zmiennych, ale jeśli chcesz serializować inne informacje, musisz dodać własny serializator. Na przykład komentarze na poziomie obszaru roboczego nie są domyślnie serializowane przez system JSON. Jeśli chcesz je zserializować, musisz zarejestrować dodatkowy serializator.

Dodatkowe narzędzia do serializacji są często używane do serializacji i deserializacji stanu wtyczki.

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

Podczas rejestrowania serializatora musisz podać kilka informacji:

• Nazwa serializatora, pod którą dane są też zapisywane.
• Funkcja save stanu wtyczki lub systemu powiązanego z serializatorem.
• Funkcja clear stanu.
• Funkcja load stanu.

• priority, który służy do określania kolejności deserializacji.

  Priorytet serializatora możesz określić na podstawie priorytetów wbudowanych

Po wywołaniu funkcji Blockly.serialization.workspaces.save zostanie wywołana funkcja save każdego serializera, a jej dane zostaną dodane do końcowych danych wyjściowych JSON:

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

Po wywołaniu Blockly.serialization.workspaces.load każdy serializator jest wywoływany według priorytetu. Serializatory o większych wartościach priorytetu są wywoływane przed serializatorami o mniejszych wartościach priorytetu.

Gdy wywołany zostanie serializator, dzieją się 2 rzeczy:

1. Wywoływana jest podana funkcja clear. Dzięki temu stan wtyczki lub systemu jest czysty, zanim zostanie załadowany kolejny stan. Na przykład serializator workspace-comments usuwa wszystkie istniejące komentarze z workspace.
2. Wywoływana jest podana funkcja load.

System XML

System XML umożliwia serializację obszaru roboczego do węzła XML. Był to pierwotny system serializacji Blockly. Został on wycofany, co oznacza, że nie będzie otrzymywać nowych funkcji. Dlatego zalecamy używanie systemu JSON, jeśli to możliwe.

Uwaga: informacje na temat migracji do JSON znajdziesz w przewodniku po migracji.

Interfejsy API

Informacje o interfejsach API systemu XML znajdziesz w dokumentacji.

Bloki do hakowania

Informacje o dodawaniu dodatkowej serializacji do bloków znajdziesz w dokumentacji dotyczącej rozszerzeń i modyfikatorów.

Zaczepy kuchenne

Informacje o serii pól znajdziesz w dokumentacji dotyczącej pol niestandardowych.

Wybór między JSON a XML

Zalecamy użycie serializatora JSON zamiast XML. System JSON umożliwia serializację stanu obszaru roboczego do obiektu JavaScript. Jest to korzystne, ponieważ:

1. Plik JSON można łatwo skompresować lub przekonwertować na inny format.
2. Format JSON jest łatwy do obsługi programowo.
3. Format JSON ułatwia rozszerzanie i dołączanie danych.

Dodatkowo system XML nie będzie już otrzymywać aktualizacji, a w porównaniu z serializatorem JSON ma mniej funkcji. Możesz na przykład zarejestrować własny serializator JSON, aby łatwo zapisywać i ładować dodatkowe dane, takie jak dane na temat dodanych wtyczek lub dostosowań. Nie jest to możliwe w systemie XML.

Jeśli zdarzyło Ci się już korzystać z serializacji XML, zapoznaj się z przewodnikiem po migracji, w którym znajdziesz informacje na temat uaktualniania.