Serializacja

Serializacja zapisuje stan obszaru roboczego, aby można go było później wczytać z powrotem do tego obszaru. Obejmuje to serializację stanu bloków, zmiennych i wtyczek, które chcesz zapisać. Wszystkie niezbędne dane możesz przekonwertować na format tekstowy, co ułatwia ich przechowywanie, a następnie wczytać je z powrotem do w pełni funkcjonalnego obszaru roboczego.

Blockly udostępnia te dane w 2 formatach: JSON i XML. Zalecamy używanie systemu JSON w nowych projektach i zachęcanie starszych projektów do uaktualniania. System XML to starszy format zapisu. Nie zostanie ona usunięta, ale nie będzie zawierać nowych funkcji.

System JSON

System serializacji JSON składa się z wielu serializatorów. Istnieją wbudowane serializatory bloków i zmiennych, a także dodatkowe. Każdy serializator odpowiada za serializację i deserializację stanu konkretnej wtyczki lub systemu.

Zapisywanie i wczytywanie

Obszary robocze

Możesz zserializować lub zserilizować stan całego obszaru roboczego, 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 zserializują lub deserializują wszystkie poszczególne systemy (reprezentowane przez serializatory), które są zarejestrowane w obszarze roboczym.

Pojedyncze bloki

Możesz serializować lub 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);

Poszczególne systemy

Możesz serializować 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 jawną kolejność deserializacji, co ułatwia zapobieganie duplikowaniu stanu w zapisaniu.

Po wywołaniu Blockly.serialization.workspaces.load serializatory otrzymują stan do deserializacji w kolejności priorytetu. Zostało to wyjaśnione dokładniej w sekcji Serializatory, a jego celem jest umożliwienie serializacji za pomocą stanu z innych systemów.

Kolejność deserializacji wbudowanych serializatorów:

  1. Zmienne są deserializowane.
  2. Blokady są deserializowane. Poszczególne stosy/bloki najwyższego poziomu są deserowane w dowolnej kolejności.
    1. Typ jest deserializowany. Powoduje to uruchomienie metody inicjowania bloku, mieszania komponentów itd.
    2. Atrybuty są deserializowane. Obejmuje to usługi, które stosują się do dowolnych blokad. Na przykład: x, y, zwinięta, wyłączona, dane itp.
    3. Dodatkowy stan zostanie poddany deserializacji. Więcej informacji znajdziesz w dokumentacji rozszerzeń i mutatorów.
    4. Bloka jest połączona z elementem nadrzędnym (jeśli istnieje).
    5. Ikony są deserializowane. Pojedyncze ikony są deserializowane w dowolnej kolejności.
    6. Pola są deserializowane. Poszczególne pola są deserializowane w dowolnej kolejności.
    7. Bloky danych wejściowych są deserializowane. Obejmuje to bloki połączone z danymi wejściowymi wartości i danymi wejściowymi instrukcji. Poszczególne dane wejściowe są deserializowane w dowolnej kolejności.
    8. Kolejne bloki są deserializowane.

Kiedy zapisywać dodatkowy stan

Jeśli w przypadku bloków elementy są w niższej kolejności, które zależą od czegoś większego w kolejności, zduplikuj te dane i dodaj je do dodatkowego stanu.

Jeśli na przykład masz pole, które istnieje tylko wtedy, gdy połączony jest kolejny blok, należy dodać do dodatkowego stanu informacje o tej następnej bloku, aby pole mogło zostać dodane do bloku, zanim jego stan zostanie zdezserialowany.

Jeśli jednak dane wejściowe istnieją tylko wtedy, gdy pole ma określoną wartość, nie musisz dodawać informacji o tym polu do dodatkowego stanu. Dzieje się tak, ponieważ najpierw stan pola będzie poddany deserializacji, a gdy już tak, możesz dodać dane wejściowe do bloku. Zwykle dodanie danych wejściowych jest aktywowane przez validator.

Pamiętaj, że reguła dotycząca duplikowania stanu powinna też uwzględniać, że stosy bloków, ikony, pola i bloki danych wejściowych są deserializowane w dowolnej kolejności. Jeśli na przykład jedno pole B istnieje tylko wtedy, gdy inne pole A ma określoną wartość, dodaj informacje o A do dodatkowego stanu na wypadek deserializacji pola B przed A.

Haki blokowe

Informacje o tym, jak dodać dodatkową serializację do bloków, znajdziesz w dokumentacji rozszerzeń i mutatorów.

Punkty haftowe

Więcej informacji o serializacji pól znajdziesz w dokumentacji pól niestandardowych.

Punkty zaczepienia serializatora

System JSON umożliwia rejestrowanie serializatorów, które zserializują i deserializują jakiś stan. Wbudowane serializatory Blockly zajmują się serializacją informacji o blokach i zmiennych, ale jeśli chcesz zseriować 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 serializatory 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, w którym są też zapisywane dane.
  • Funkcja save określająca stan wtyczki/systemu powiązanego z serializatorem.
  • Funkcja clear stanu.
  • Funkcja load stanu.

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

    Priorytet serializacji może być uzależniony od wbudowanych priorytetów.

Po wywołaniu Blockly.serialization.workspaces.save funkcja save każdej serializacji zostanie wywołana, a jej dane zostaną dodane do końcowego pliku JSON:

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

Gdy wywołanie Blockly.serialization.workspaces.load jest wywoływane, każdy serializator jest wywoływany w kolejności od priorytetu. Serializatory o większej dodatniej wartości priorytetu są uruchamiane przed serializatorami o mniej dodatnich wartościach priorytetu.

Po uruchomieniu serializatora zachodzą 2 rzeczy:

  1. Wywoływana jest podana funkcja clear. Dzięki temu stan wtyczki/systemu jest czysty przed wczytaniem kolejnych stanów. Na przykład użycie serializatora workspace-comments usuwa z obszaru roboczego wszystkie istniejące komentarze.
  2. Wywoływana jest podana funkcja load.

System XML

System XML umożliwia serializację obszaru roboczego do postaci węzła XML. To był oryginalny system serializacji Blockly. Obecnie umieszczono go w pudełku po lodówce, co oznacza, że nie będzie korzystać z nowych funkcji. Dlatego zalecamy, aby w miarę możliwości korzystać z systemu JSON.

Interfejsy API

Informacje o interfejsach API systemu XML znajdziesz w dokumentacji referencyjnej.

Haki blokowe

Informacje o tym, jak dodać dodatkową serializację do bloków, znajdziesz w dokumentacji rozszerzeń i mutatorów.

Punkty haftowe

Więcej informacji o serializacji pól znajdziesz w dokumentacji pól niestandardowych.

Wybór między JSON a XML

Zalecamy stosowanie serializatora JSON zamiast XML. System JSON umożliwia serializację stanu obszaru roboczego w obiekt JavaScript. Jest to korzystne, ponieważ:

  1. Plik JSON można łatwo skompresować lub przekonwertować na inny format.
  2. Praca z użyciem kodu JSON jest łatwa.
  3. Kod JSON można łatwo rozszerzyć i dołączyć dane.

Poza tym system XML nie będzie otrzymywać aktualizacji i nie będzie już miał żadnych funkcji w porównaniu z serializatorem JSON. Możesz na przykład zarejestrować własny serializator JSON, aby łatwo zapisywać i wczytywać dodatkowe dane, takie jak dane na potrzeby wtyczek lub dostosowań. Nie jest to możliwe w systemie XML.

Jeśli wcześniej zdarzyło Ci się korzystać z serializacji XML, odpowiednie informacje znajdziesz w przewodniku po migracji.