Serialización

La serialización guarda el estado de tu lugar de trabajo para que pueda volver a cargarse en él más tarde. Esto incluye la serialización del estado de cualquier bloque, variable o complemento que quieras guardar. Puedes convertir todos los datos que necesitas guardar a un formato basado en texto para un almacenamiento sencillo y, luego, volver a cargarlos en un lugar de trabajo funcional por completo.

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

Sistema JSON

Nota: Si deseas obtener información para migrar a JSON desde XML, 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.

Guardando y cargando

Lugares de trabajo

Puedes serializar o deserializar el estado de un lugar de trabajo completo si llamas 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 se registran con el lugar de trabajo.

Bloques individuales

Puedes serializar o deserializar bloques individuales llamando 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, lo que facilita la prevención de la duplicación del estado en un guardado.

Cuando se llama a Blockly.serialization.workspaces.load, los serializadores tienen el estado para deserializarse 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 la deserialización de los 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 deserializan en un orden arbitrario.
   1. Se deserializa el tipo. Esto construye el bloque, activa su método init y mezcla las extensiones.
   2. Los atributos se deserializan. Esto incluye las propiedades que pueden aplicarse a cualquier bloque. Por ejemplo: x, y, contraído, inhabilitado y datos.
   3. Se deserializa el estado adicional. Consulta la documentación de Extensiones y mutadores para obtener más información.
   4. El bloque está conectado a su elemento superior (si existe).
   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. Los bloques de entrada se deserializan. Esto incluye los bloques conectados a entradas de valor y entradas de instrucción. Las entradas individuales se deserializan en un orden arbitrario.
   8. Los siguientes bloques se deserializan.

Cuándo guardar el estado adicional

Para los bloques, si tienes un elemento inferior en el orden que depende de otro superior en el orden, debes duplicar esos datos y agregarlos a tu estado adicional.

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

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

Ten en cuenta que la regla sobre la duplicación de estados 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.

Bloques de ganchos

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

Hooks de campo

Si deseas obtener información para serializar campos, consulta la documentación Campos personalizados.

Hooks del serializador

El sistema JSON te permite registrar serializadores que serializan y deserializan algún estado. Los serializadores integrados de Blockly se encargan de serializar información sobre bloques y variables, pero si deseas 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 deseas 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 lo siguiente:

• Un nombre para el serializador, con 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 del 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 final de JSON:

{
  "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, ocurren dos cosas:

1. Se llama a la función clear proporcionada. Esto garantiza que el estado de tu complemento o sistema esté limpio antes de que se carguen más estados. Por ejemplo, el serializador de workspace-comments quitaría todos los comentarios existentes del lugar 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 fue el sistema de serialización original de Blockly. Ya se bloqueó, lo que significa que no recibirá funciones nuevas. Por lo tanto, te recomendamos usar el sistema JSON si es posible.

Nota: Si deseas obtener información para migrar a JSON, consulta la guía de migración.

APIs

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

Bloques de ganchos

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

Hooks de campo

Si deseas obtener información para serializar campos, consulta la documentación Campos personalizados.

Elige entre JSON y XML

Recomendamos el serializador JSON en lugar de XML. El sistema JSON te permite serializar el estado de tu lugar 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 manera 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 JSON para guardar y cargar con facilidad datos adicionales, como datos para complementos o personalizaciones que hayas agregado. 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.