Serialización

La serialización guarda el estado de tu espacio de trabajo para que se pueda volver a cargar más adelante. Esto incluye serializar el estado de cualquier bloque, variable o complemento que desees guardar. Puedes convertir todos los datos que necesites guardar en un formato basado en texto para un almacenamiento fácil y, luego, volver a cargarlos en un lugar de trabajo completamente funcional más adelante.

Blockly proporciona dos formatos para estos datos: JSON y XML. Recomendamos usar el sistema JSON para los proyectos nuevos y recomendamos que los proyectos más antiguos que usan XML se actualicen. El sistema XML es el formato de guardado heredado. No se quitará, pero no recibirá funciones nuevas.

Sistema JSON

Nota: Para obtener información sobre cómo migrar de XML a JSON, consulta la guía de migración.

El sistema de serialización JSON consta de varios serializadores. Hay serializadores integrados para bloques y variables, y también puedes registrar serializadores adicionales. Cada serializador es responsable de serializar y deserializar el estado de un complemento o sistema en particular.

Guardado y carga

Lugares de trabajo

Puedes serializar o deserializar el estado de un lugar de trabajo completo llamando a los métodos save y load en el espacio de nombres workspaces.

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

Estas llamadas serializan o deserializan todos los sistemas individuales (representados por serializadores) que están registrados en el espacio de trabajo.

Bloques individuales

Para serializar o deserializar bloques individuales, llama a los métodos save y append en el espacio de nombres blocks.

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

Sistemas individuales

Puedes serializar o deserializar sistemas individuales (p. ej., bloques, variables, complementos, etc.) si construyes el serializador asociado y llamas a sus métodos save y 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);

Orden de deserialización

El sistema JSON tiene un orden de deserialización explícito, que facilita la prevención de la duplicación del estado dentro de un guardado.

Cuando se llama a Blockly.serialization.workspaces.load, a los serializadores se les asigna un estado para deserializar en orden de prioridad. Esto se explica con más detalle en la sección Serializadores, y su propósito es permitir que los serializadores dependan del estado de otros sistemas.

El orden de deserialización de serializadores integrados es el siguiente:

1. Los modelos de variables se deserializan.
2. Los modelos de procedimiento se deserializan.
3. Los bloques se deserializan. Los bloques individuales de nivel superior se desserializan en un orden arbitrario.
   1. Se deserializa el tipo. Esto construye el bloque, activa su método de inicialización y combina las extensiones.
   2. Los atributos se deserializan. Esto incluye las propiedades que se pueden aplicar a cualquier bloque. Por ejemplo: x, y, colapsado, inhabilitado y datos.
   3. Se deserializa el estado adicional. Consulta la documentación sobre Extensiones y mutadores para obtener más información.
   4. El bloque está conectado a su elemento superior (si existe uno).
   5. Los íconos se deserializan. Los íconos individuales se deserializan en un orden arbitrario.
   6. Los campos se deserializan. Los campos individuales se deserializan en un orden arbitrario.
   7. Se deserializan los bloques de entrada. Esto incluye bloques conectados a entradas de valor y entradas de sentencia. Las entradas individuales se deserializan en un orden arbitrario.
   8. Los siguientes bloques se deserializan.

Cuándo guardar estados adicionales

En el caso de los bloques, si tienes algo más bajo en el orden que depende de algo más alto en el orden, debes duplicar esos datos y agregarlos a tu estado adicional.

Por ejemplo, si tienes un campo que solo existe si el siguiente bloque está conectado, debes agregar información sobre ese bloque a tu estado adicional, de modo que el campo se pueda agregar a tu bloque antes de que el estado del campo se deserialice.

Sin embargo, si tienes una entrada que solo existe si un campo tiene un valor determinado, no es necesario que agregues información sobre el campo a tu estado adicional. Esto se debe a que el estado de tu campo se deserializará primero y, cuando sea así, podrás agregar la entrada a tu bloque. Por lo general, agregar la entrada se activará con un validador.

Ten en cuenta que la regla sobre el estado de duplicación también debe tener en cuenta que las pilas de bloques, los íconos, los campos y los bloques de entrada se deserializan en un orden arbitrario. Por ejemplo, si tienes un campo B que solo existe si otro campo A tiene un valor determinado, debes agregar información sobre A a tu estado adicional en caso de que B se deserialice antes que A.

Hooks de bloqueo

Para obtener información sobre cómo agregar serialización adicional a los bloques, consulta la documentación Extensiones y mutadores.

Hooks de campo

Para obtener información sobre cómo serializar campos, consulta la documentación Campos personalizados.

Hooks de serializador

El sistema JSON te permite registrar serializadores que serializan y deserializan algunos estados. Los serializadores integrados de Blockly se encargan de serializar información sobre bloques y variables, pero si quieres serializar otra información, deberás agregar tu propio serializador. Por ejemplo, el sistema JSON no serializa los comentarios a nivel del lugar de trabajo de forma predeterminada. Si quieres serializarlos, deberás registrar un serializador adicional.

A menudo, se usan serializadores adicionales para serializar y deserializar el estado de un complemento.

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

Cuando registras un serializador, debes proporcionar varios elementos:

• Un nombre para el serializador, en el que también se guardan los datos.
• Una función para save el estado del complemento o sistema asociado con el serializador.
• Una función para clear el estado.
• Una función para load el estado.

• Un priority, que se usa para determinar el orden de deserialización.

  Puedes basar la prioridad de tu serializador en las prioridades integradas.

Cuando se llame a Blockly.serialization.workspaces.save, se llamará a la función save de cada serializador y sus datos se agregarán al resultado JSON final:

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

Cuando se llama a Blockly.serialization.workspaces.load, cada serializador se activa en orden de prioridad. Los serializadores con valores de prioridad más positivos se activan antes que los serializadores con valores de prioridad menos positivos.

Cuando se activa un serializador, suceden dos cosas:

1. Se llama a la función clear proporcionada. Esto garantiza que el estado de tu plugin o sistema esté limpio antes de que se cargue más estado. Por ejemplo, el serializador de comentarios de Workspace quitaría todos los comentarios existentes del espacio de trabajo.
2. Se llama a la función load proporcionada.

Sistema XML

El sistema XML te permite serializar tu espacio de trabajo en un nodo XML. Este era el sistema de serialización original de Blockly. Ahora está en la lista de espera, lo que significa que no recibirá funciones nuevas. Por lo tanto, te recomendamos que uses el sistema JSON si es posible.

Nota: Para obtener información sobre cómo migrar a JSON, consulta la guía de migración.

API

Para obtener información sobre las APIs del sistema XML, consulta la documentación de referencia.

Hooks de bloqueo

Si deseas obtener información para agregar serialización adicional a los bloques, consulta la documentación de Extensiones y mutadores.

Hooks de campo

Para obtener información sobre cómo serializar campos, consulta la documentación de Campos personalizados.

Elige entre JSON y XML

Recomendamos el serializador JSON en lugar del XML. El sistema JSON te permite serializar el estado de tu espacio de trabajo en un objeto JavaScript. Esto es ventajoso por los siguientes motivos:

1. JSON es fácil de comprimir o convertir a otro formato.
2. Es fácil trabajar con JSON de forma programática.
3. JSON es fácil de extender y agregar datos.

Además, el sistema XML ya no recibirá actualizaciones y ya carece de funciones en comparación con el serializador JSON. Por ejemplo, puedes registrar tu propio serializador de JSON para guardar y cargar datos adicionales con facilidad, como los datos de los complementos o las personalizaciones que agregaste. Esto no es posible en el sistema XML.

Si ya usaste la serialización XML, consulta la guía de migración para obtener información sobre cómo actualizar.