serialização

A serialização está salvando o estado do espaço de trabalho para que possa ser carregado novamente no espaço de trabalho posteriormente. Isso inclui a serialização do estado de todos os blocos, variáveis ou plug-ins que você quer salvar. É possível converter todos os dados que você precisa salvar em um formato de texto para facilitar o armazenamento e depois carregar esses dados novamente em um espaço de trabalho totalmente funcional.

O Blockly fornece dois formatos para esses dados: JSON e XML. Recomendamos o uso do sistema JSON para novos projetos e incentivamos projetos mais antigos que usam XML para fazer upgrade. O sistema XML é o formato de salvamento legado. Ela não será removida, mas não receberá novos recursos.

Sistema JSON

Observação: para informações sobre como migrar para JSON do XML, 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 serializadores adicionais. Cada serializador é responsável por serializar e desserializar o estado de um plug-in ou sistema específico.

Como 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 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 dele.

// 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 a prevenção da duplicação do estado em um salvamento.

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

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

1. As variáveis estão desserializadas.
2. Os blocos estão desserializados. Pilhas individuais ou blocos de nível superior são desserializados em uma ordem arbitrária.
   1. O tipo é desserializado. Isso aciona o método init do bloco, mistura em extensões etc.
   2. Os atributos estão desserializados. Isso inclui propriedades que podem ser aplicadas a qualquer bloco. Por exemplo: x, y, recolhido, desativado, dados etc.
   3. O estado extra está desserializado. Consulte a documentação Extensões e Mutadores para mais informações.
   4. O bloco está conectado ao pai (se houver).
   5. Os ícones são desserializados. Ícones individuais são desserializados em uma ordem arbitrária.
   6. Os campos estã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ções. As entradas individuais são desserializadas em uma ordem arbitrária.
   8. Os próximos blocos estão desserializados.

Quando salvar um estado extra

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

Por exemplo, se você tiver um campo que só existe se um próximo bloco 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 estiver, você poderá adicionar a entrada ao bloco. Geralmente, a inclusão da entrada será acionada por um validador.

Observe que a regra sobre duplicação de estado também precisa considerar que pilhas de bloco, ícones, campos e blocos de entrada são desserializados em uma ordem arbitrária. Por exemplo, se você tiver um campo B que só exista 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 informações sobre como adicionar serialização extra a blocos, consulte a documentação Extensões e Mutadores.

Ganchos de campo

Para informações sobre como serializar campos, consulte a documentação sobre 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, 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 serializá-los, será necessário registrar outro serializador.

Os serializadores adicionais geralmente 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, 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.

  Você pode basear a prioridade do serializador nas prioridades integradas

Quando Blockly.serialization.workspaces.save for chamado, a função save de cada serializador será chamada, e os dados 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 seja limpo antes que outro estado seja carregado. Por exemplo, o serializador de comentários do 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 o espaço de trabalho em um nó XML. Esse era o sistema original de serialização do Blockly. Ele foi colocado no gelo, o que significa que não receberá novos recursos. Por isso, recomendamos usar o sistema JSON, se possível.

Observação: para 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.

Ganchos para blocos

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

Ganchos de campo

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

Como escolher entre JSON e XML

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

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

Além disso, o sistema XML não receberá mais 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 para 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 informações sobre como fazer upgrade.