Serialização

A serialização salva o estado do espaço de trabalho para que ele possa ser carregado de volta mais tarde. Isso inclui a serialização do estado de todos os blocos, variáveis ou plug-ins que você queira salvar. É possível converter todos os dados que você precisa salvar em um formato baseado em texto para facilitar o armazenamento e, em seguida, carregar esses dados de volta em um espaço de trabalho totalmente funcional.

O Blockly fornece dois formatos para esses dados: JSON e XML. Recomendamos usar o sistema JSON para novos projetos e encorajar projetos mais antigos usando XML para fazer upgrade. O sistema XML é o formato de salvamento legado. Ele não será removido, mas não receberá novos recursos.

Sistema JSON

O sistema de serialização JSON é composto de 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 desserializar o estado de um plug-in ou sistema específico.

Salvar e carregar

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 com o 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 de estado em um salvamento.

Quando Blockly.serialization.workspaces.load é chamado, os serializadores recebem um estado para desserializar em ordem de prioridade. Isso é explicado mais adiante na seção Serializadores, e a finalidade dela é permitir que os serializadores dependam do estado de outros sistemas.

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

  1. Os modelos de variáveis são desserializados.
  2. Os modelos de procedimento são desserializados.
  3. Os blocos são desserializados. Os blocos individuais de nível superior são desserializados em uma ordem arbitrária.
    1. O tipo é desserializado. Isso constrói o bloco, aciona o método "init" dele e combina as extensões.
    2. Os atributos são desserializados. Isso inclui propriedades que podem ser aplicadas a qualquer bloco. Por exemplo: x, y, recolhido, 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. Ícones individuais são desserializados em uma ordem arbitrária.
    6. Os campos são desserializados. Os 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. Entradas individuais são desserializadas em uma ordem arbitrária.
    8. Os próximos blocos são desserializados.

Quando salvar o estado extra

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

Por exemplo, se você tiver um campo que só existe se um bloco seguinte estiver 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 se um campo tiver 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 ocorrer, será possível adicionar a entrada ao bloco. Normalmente, a adição da entrada é acionada por um validator.

Observe que a regra sobre a duplicação de estado também precisa considerar que pilhas de blocos, ícones, campos e blocos de entrada são desserializados em uma ordem arbitrária. 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 blocos

Para conferir informações sobre como adicionar serialização extra aos blocos, consulte a documentação Extensões e Mutadores.

Ganchos de campo

Para mais informações sobre como serializar campos, consulte a documentação Campos personalizados.

Ganchos do 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, precisará 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 quiser serializá-los, será necessário registrar mais um serializador.

Frequentemente, outros serializadores são usados 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, no qual 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.

    É possível basear a prioridade do serializador nas prioridades integradas.

Quando Blockly.serialization.workspaces.save for chamado, cada função save do serializador será chamada, e os dados relacionados serã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 de espaço de trabalho removeria todos os comentários existentes do espaço de trabalho.
  2. A função load fornecida é chamada.

Sistema XML

O sistema XML permite serializar seu espaço de trabalho como um nó XML. Esse era o sistema de serialização original do Blockly. Agora ele está com o icebox definido e não vai receber novos recursos. Por isso, recomendamos usar o sistema JSON, se possível.

APIs

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

Ganchos para blocos

Para conferir informações sobre como adicionar serialização extra aos blocos, consulte a documentação Extensões e Mutadores.

Ganchos de campo

Para mais informações sobre como serializar campos, consulte a documentação Campos personalizados.

Como escolher entre JSON e XML

Recomendamos o serializador JSON em vez de 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 o 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, você pode registrar seu próprio serializador JSON para salvar e carregar facilmente outros dados, como os 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, consulte o guia de migração para saber como fazer upgrade.