Serializzazione in corso...

La serializzazione salva lo stato dell'area di lavoro in modo da poterla caricare nuovamente in un secondo momento. Ciò include la serializzazione dello stato di blocchi, variabili o plug-in che vuoi salvare. Puoi convertire tutti i dati che devi salvare in un formato di testo per una facile archiviazione e poi caricarli nuovamente in un'area di lavoro completamente funzionale in un secondo momento.

Blockly offre due formati per questi dati: JSON e XML. Ti consigliamo di utilizzare il sistema JSON per i nuovi progetti e di incoraggiare l'upgrade dei progetti meno recenti utilizzando il formato XML. Il sistema XML è il formato di salvataggio precedente. Non verrà rimosso, ma non riceverà nuove funzionalità.

Sistema JSON

Nota: per informazioni su come eseguire la migrazione a JSON da XML, consulta la guida alla migrazione.

Il sistema di serializzazione JSON è composto da più serializzatori. Esistono serializzatori integrati per blocchi e variabili e puoi anche registrare serializzatori aggiuntivi. Ogni serializzatore è responsabile della serializzazione e deserializzazione dello stato di un determinato plug-in o sistema.

Salvataggio e caricamento

Aree di lavoro

Puoi serializzare o deserializzare lo stato di un'intera area di lavoro chiamando i metodi save e load nello spazio dei nomi workspaces.

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

Queste chiamate serializzano o deserializzano tutti i singoli sistemi (rappresentati dai serializzatori) registrati nell'area di lavoro.

Singoli blocchi

Puoi serializzare o deserializzare i singoli blocchi chiamando i metodi save e append nello spazio dei nomi blocks.

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

Sistemi singoli

Puoi serializzare o deserializzare singoli sistemi (ad es. blocchi, variabili, plug-in e così via) creando il serializzatore associato e chiamando i relativi metodi save e 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);

Ordine di deserializzazione

Il sistema JSON ha un ordine di deserializzazione esplicito, che semplifica la prevenzione della duplicazione dello stato all'interno di un salvataggio.

Quando viene chiamato Blockly.serialization.workspaces.load, ai serializzatori viene assegnato lo stato di deserializzazione in ordine di priorità. La procedura è spiegata più in dettaglio nella sezione Serializzatori e il suo scopo è consentire ai serializzatori di dipendere dallo stato di altri sistemi.

L'ordine per la deserializzazione dei serializzatori integrati è:

1. Le variabili vengono deserializzate.
2. I blocchi vengono deserializzati. I singoli stack/blocchi di primo livello vengono deserializzati in un ordine arbitrario.
   1. Il tipo è deserializzato. Questo attiva il metodo di inizializzazione del blocco, combina le estensioni e così via.
   2. Gli attributi vengono deserializzati. Sono incluse le proprietà che possono essere applicate a qualsiasi blocco. Ad esempio: x, y, compresso, disabilitato, dati ecc.
   3. Lo stato extra viene deserializzato. Per ulteriori informazioni, consulta la documentazione su Estensioni e modifiche.
   4. Il blocco è collegato al blocco principale (se esistente).
   5. Le icone vengono deserializzate. Le singole icone vengono deserializzate in un ordine arbitrario.
   6. I campi vengono deserializzati. I singoli campi vengono deserializzati in un ordine arbitrario.
   7. I blocchi di input sono deserializzati. Sono inclusi i blocchi collegati a input di valori e input di istruzioni. I singoli input vengono deserializzati in un ordine arbitrario.
   8. I blocchi successivi vengono deserializzati.

Quando salvare lo stato aggiuntivo

Per i blocchi, se hai un elemento più basso nell'ordine che dipende da qualcosa di più alto nell'ordine, devi duplicare quei dati e aggiungerli allo stato extra.

Ad esempio, se hai un campo che esiste solo se è collegato un blocco successivo, devi aggiungere le relative informazioni allo stato aggiuntivo, in modo che il campo possa essere aggiunto al blocco prima che lo stato del campo venga deserializzato.

Tuttavia, se un input esiste solo se un campo ha un determinato valore, non è necessario aggiungere informazioni sul campo allo stato aggiuntivo. Questo perché lo stato del campo verrà prima deserializzato e, in quel caso, potrai aggiungere l'input al blocco. In genere l'aggiunta dell'input viene attivata da uno validator.

Tieni presente che la regola sulla duplicazione dello stato dovrebbe anche tenere conto del fatto che stack di blocchi, icone, campi e blocchi di input vengono deserializzati in un ordine arbitrario. Ad esempio, se un campo B esiste solo se l'altro campo A ha un determinato valore, devi aggiungere informazioni su A allo stato aggiuntivo nel caso in cui B venga deserializzato prima di A.

Ganci di blocco

Per informazioni su come aggiungere un'ulteriore serializzazione ai blocchi, consulta la documentazione su estensioni e modifiche.

Hook da campo

Per informazioni su come serializzare i campi, consulta la documentazione sui campi personalizzati.

Hook del serializzatore

Il sistema JSON consente di registrare serializzatori che serializzano e deserializzano alcuni stati. I serializzatori integrati di Blockly si occupano della serializzazione delle informazioni su blocchi e variabili, ma se vuoi serializzare altre informazioni dovrai aggiungere il tuo serializzatore. Ad esempio, i commenti a livello di area di lavoro non vengono serializzati per impostazione predefinita dal sistema JSON. Se vuoi serializzarli, dovrai registrare un serializzatore aggiuntivo.

Per serializzare e deserializzare lo stato di un plug-in vengono spesso utilizzati serializzatori aggiuntivi.

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

Quando registri un serializzatore, devi fornire diversi elementi:

• Un nome per il serializzatore, in cui vengono salvati anche i dati.
• Una funzione per save lo stato del plug-in/sistema associato al serializzatore.
• Una funzione per clear lo stato.
• Una funzione per load lo stato.

• Un elemento priority, utilizzato per determinare l'ordine di deserializzazione.

  Puoi basare la priorità del serializzatore sulle priorità integrate

Quando viene chiamato Blockly.serialization.workspaces.save, viene chiamata la funzione save di ogni serializzatore e i relativi dati vengono aggiunti all'output JSON finale:

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

Quando viene chiamato Blockly.serialization.workspaces.load, ogni serializzatore viene attivato in ordine di priorità. I serializzatori con più valori di priorità positivi vengono attivati prima dei serializzatori con valori di priorità meno positivi.

Quando viene attivato un serializzatore, si verificano due cose:

1. Viene richiamata la funzione clear fornita. Ciò garantisce che lo stato del plug-in/sistema sia pulito prima che vengano caricati altri stati. Ad esempio, il serializzatore workspace-comments rimuove tutti i commenti esistenti dall'area di lavoro.
2. Viene richiamata la funzione load fornita.

Sistema XML

Il sistema XML ti consente di serializzare l'area di lavoro in un nodo XML. Questo era il sistema di serializzazione originale di Blockly. È stata racchiusa in ghiaccio, quindi non riceverà nuove funzionalità. Di conseguenza, consigliamo di usare il sistema JSON, se possibile.

Nota: per informazioni su come eseguire la migrazione a JSON, consulta la guida alla migrazione.

API

Per informazioni sulle API del sistema XML, consulta la documentazione di riferimento.

Ganci di blocco

Per informazioni su come aggiungere un'ulteriore serializzazione ai blocchi, consulta la documentazione su estensioni e modifiche.

Hook da campo

Per informazioni su come serializzare i campi, consulta la documentazione sui campi personalizzati.

Scegliere tra JSON e XML

Consigliamo il serializzatore JSON rispetto a XML. Il sistema JSON ti consente di serializzare lo stato dell'area di lavoro a un oggetto JavaScript. Ciò è vantaggioso perché:

1. JSON è facile da comprimere o convertire in un altro formato.
2. È facile lavorare con JSON in modo programmatico.
3. JSON è facile da estendere e aggiungere dati.

Inoltre, il sistema XML non riceverà più aggiornamenti e manca già di funzionalità rispetto al serializzatore JSON. Ad esempio, puoi registrare il tuo serializzatore JSON per salvare e caricare facilmente ulteriori dati, come i dati per i plug-in o le personalizzazioni che hai aggiunto. Ciò non è possibile nel sistema XML.

Se hai già utilizzato la serializzazione XML, consulta la guida alla migrazione per informazioni su come eseguire l'upgrade.