Serialização

A serialização salva o estado do seu espaço de trabalho para que ele possa ser carregado novamente mais tarde. Isso inclui a serialização do estado de qualquer bloco, variável ou plug-in que você quer salvar. Você pode converter todos os dados que precisa salvar em um formato baseado em texto para facilitar o armazenamento e, depois, carregar esses dados em um espaço de trabalho totalmente funcional.

O Blockly oferece dois formatos para esses dados: JSON e XML. Recomendamos o uso do sistema JSON para novos projetos e incentivamos os projetos mais antigos a usar XML para fazer upgrade. O sistema XML é o formato de salvamento legado. Ele não será removido, mas não vai receber novos recursos.

Sistema JSON

Observação: para mais informações sobre como migrar do XML para JSON, consulte o guia de migração.

O sistema de serialização JSON é composto por vários serializadores. Há serializadores integrados para blocos e variáveis, e você também pode registrar outros serializadores. Cada serializador é responsável por serializar e deserializar o estado de um plug-in ou sistema específico.

Salvando e carregando

Espaços de trabalho

É possível serializar ou desserializar o estado de um espaço de trabalho inteiro chamando os métodos save e load no namespace workspaces.

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

Essas chamadas serializam ou desserializam todos os sistemas individuais (representados por serializadores) registrados no espaço de trabalho.

Blocos individuais

É possível serializar ou desserializar blocos individuais chamando os métodos save e append no namespace blocks.

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

Sistemas individuais

É possível serializar ou desserializar sistemas individuais (por exemplo, blocos, variáveis, plug-ins etc.) construindo o serializador associado e chamando os métodos 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);

Ordem de desserialização

O sistema JSON tem uma ordem de desserialização explícita, o que facilita evitar a duplicação do estado ao salvar.

Quando Blockly.serialization.workspaces.load é chamado, os serializadores recebem o estado para desserialização na ordem de prioridade. Isso é explicado mais detalhadamente na seção Serializadores e tem como objetivo permitir que os serializadores dependam do estado de outros sistemas.

A ordem de desserialização de serializadores integrados é:

1. Os modelos de variáveis são desserializados.
2. Os modelos de procedimento são desserializados.
3. Os blocos são desserializados. Blocos de nível superior individuais são desserializados em uma ordem arbitrária.
   1. O tipo é desserializado. Isso constrói o bloco, aciona o método de inicialização e mistura extensões.
   2. Os atributos são desserializados. Isso inclui propriedades que podem ser aplicadas a qualquer bloco. Por exemplo: x, y, fechado, desativado e dados.
   3. O estado extra é desserializado. Consulte a documentação Extensões e Mutadores para mais informações.
   4. O bloco está conectado ao pai (se houver um).
   5. Os ícones são desserializados. Os ícones individuais são desserializados em uma ordem arbitrária.
   6. Os campos são desserializados. Campos individuais são desserializados em uma ordem arbitrária.
   7. Os blocos de entrada são desserializados. Isso inclui blocos conectados a entradas de valor e de instrução. As entradas individuais são desserializadas em uma ordem arbitrária.
   8. Os blocos seguintes são desserializados.

Quando salvar o estado extra

Para blocos, se você tiver algo mais baixo na ordem que depende de algo mais alto na ordem, duplique esses dados e adicione-os ao estado extra.

Por exemplo, se você tiver um campo que só existe quando um próximo bloco está conectado, adicione informações sobre esse próximo bloco ao estado extra para que o campo possa ser adicionado ao bloco antes que o estado do campo seja desserializado.

No entanto, se você tiver uma entrada que só existe quando um campo tem um determinado valor, não será necessário adicionar informações sobre o campo ao estado extra. Isso ocorre porque o estado do campo será desserializado primeiro e, quando isso acontecer, você poderá adicionar a entrada ao seu bloco. Normalmente, a adição da entrada é acionada por um validador.

A regra sobre duplicação de estado também precisa considerar que pilhas de blocos, ícones, campos e blocos de entrada são desserializados em uma ordem arbitraria. Por exemplo, se você tiver um campo B que só existe se outro campo A tiver um determinado valor, adicione informações sobre A ao estado extra caso B seja desserializado antes de A.

Ganchos

Para informações sobre como adicionar mais serialização a blocos, consulte a documentação Extensões e mutatores.

Ganchos de campo

Para saber como serializar campos, consulte a documentação Campos personalizados.

Hooks de serializador

O sistema JSON permite registrar serializadores que serializam e desserializam algum estado. Os serializadores integrados do Blockly cuidam da serialização de informações sobre blocos e variáveis, mas, se você quiser serializar outras informações, será necessário adicionar seu próprio serializador. Por exemplo, os comentários no nível do espaço de trabalho não são serializados por padrão pelo sistema JSON. Se você quiser serializar, será necessário registrar um serializador adicional.

Outros serializadores são usados com frequência para serializar e desserializar o estado de um plug-in.

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

Ao registrar um serializador, você precisa fornecer várias informações:

• Um nome para o serializador, em que os dados também são salvos.
• Uma função para save o estado do plug-in/sistema associado ao serializador.
• Uma função para clear o estado.
• Uma função para load o estado.

• Um priority, que é usado para determinar a ordem de desserialização.

  Baseie a prioridade do serializador nas prioridades integradas.

Quando Blockly.serialization.workspaces.save é chamado, a função save de cada serializador é chamada e os dados são adicionados à saída JSON final:

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

Quando Blockly.serialization.workspaces.load é chamado, cada serializador é acionado em ordem de prioridade. Os serializadores com valores de prioridade mais positivos são acionados antes dos serializadores com valores de prioridade menos positivos.

Quando um serializador é acionado, duas coisas acontecem:

1. A função clear fornecida é chamada. Isso garante que o estado do plug-in/sistema esteja limpo antes que mais estados sejam carregados. Por exemplo, o serializador de comentários do espaço de trabalho remove todos os comentários do espaço de trabalho.
2. A função load fornecida é chamada.

Sistema XML

O sistema XML permite que você serialize seu espaço de trabalho em um nó XML. Esse era o sistema de serialização original do Blockly. Ele foi desativado, o que significa que não vai receber novos recursos. Portanto, recomendamos o uso do sistema JSON, se possível.

Observação :para mais informações sobre como migrar para JSON, consulte o guia de migração.

APIs

Para informações sobre as APIs do sistema XML, consulte a documentação de referência.

Hooks de bloco

Para saber mais sobre como adicionar serialização extra aos blocos, consulte a documentação Extensões e mutadores.

Hooks de campo

Para saber como serializar campos, consulte a documentação Campos personalizados.

Como escolher entre JSON e XML

Recomendamos o serializador JSON em vez do XML. O sistema JSON permite serializar o estado do espaço de trabalho para um objeto JavaScript. Isso é vantajoso porque:

1. O JSON é fácil de compactar ou converter para outro formato.
2. É fácil trabalhar com JSON de forma programática.
3. É fácil estender e anexar dados ao JSON.

Além disso, o sistema XML não vai mais receber atualizações e já não tem recursos em comparação com o serializador JSON. Por exemplo, é possível registrar seu próprio serializador JSON para salvar e carregar dados adicionais com facilidade, como dados de plug-ins ou personalizações que você adicionou. Isso não é possível no sistema XML.

Se você já usou a serialização XML anteriormente, consulte o guia de migração para informações sobre como fazer upgrade.