Salvar e carregar

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 o 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

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.

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.

// 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 de duplicação de estado em um salvamento.

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 dos 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. 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 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.
  4. O estado extra é desserializado. Consulte a documentação de Mutators para mais informações.
  5. O bloco está conectado ao familiar responsável (se houver um).
    1. Os ícones são desserializados. Os ícones individuais são desserializados em uma ordem arbitrária.
    2. Os campos são desserializados. Campos individuais são desserializados em uma ordem arbitrária.
    3. 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.
    4. Os próximos blocos são desserializados.

Quando salvar um 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. Quando isso acontecer, você poderá adicionar a entrada ao bloco. Normalmente, a adição da entrada é acionada por um validador.

A regra sobre a duplicação do estado também precisa levar em conta 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.

Bloquear hooks

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

Hooks 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.

    É possível basear 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. Por isso, recomendamos o uso do sistema JSON, se possível.

APIs

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

Bloquear hooks

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

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 que você serialize o estado do seu espaço de trabalho em 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, consulte o guia de migração para informações sobre como fazer upgrade.