Сериализация

Сериализация сохраняет состояние вашего рабочего пространства, чтобы его можно было загрузить обратно в рабочее пространство позже. Это включает в себя сериализацию состояния любых блоков, переменных или плагинов, которые вы хотите сохранить. Вы можете преобразовать все данные, которые необходимо сохранить, в текстовый формат для удобного хранения, а затем загрузить эти данные обратно в полнофункциональное рабочее пространство позже.

Blockly предоставляет два формата этих данных: JSON и XML. Мы рекомендуем использовать систему JSON для новых проектов и рекомендуем обновить старые проекты, использующие XML. Система XML — это устаревший формат сохранения. Он не будет удален, но новых возможностей не получит.

система JSON

Примечание. Информацию о том, как перейти на JSON из XML, см. в руководстве по миграции .

Система сериализации JSON состоит из нескольких сериализаторов. Есть встроенные сериализаторы для блоков и переменных, также вы можете зарегистрировать дополнительные сериализаторы. Каждый сериализатор отвечает за сериализацию и десериализацию состояния конкретного плагина или системы.

Сохранение и загрузка

Рабочие пространства

Вы можете сериализовать или десериализовать состояние всей рабочей области, вызвав методы save и load в пространстве имен workspaces .

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

Эти вызовы сериализуют или десериализуют все отдельные системы (представленные сериализаторами), зарегистрированные в рабочей области.

Отдельные блоки

Вы можете сериализовать или десериализовать отдельные блоки, вызывая методы save и append в пространстве имен blocks .

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

Индивидуальные системы

Вы можете сериализовать или десериализовать отдельные системы (например, блоки, переменные, плагины и т. д.), создав соответствующий сериализатор и вызвав его методы save и 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);

Порядок десериализации

Система JSON имеет явный порядок десериализации, что упрощает предотвращение дублирования состояния при сохранении.

При вызове Blockly.serialization.workspaces.load сериализаторам предоставляется состояние для десериализации в порядке приоритета . Это объясняется далее в разделе «Сериализаторы» , и его цель — позволить сериализаторам зависеть от состояния других систем.

Порядок десериализации встроенных сериализаторов:

1. Модели переменных десериализуются.
2. Модели процедур десериализуются.
3. Блоки десериализуются. Отдельные блоки верхнего уровня десериализуются в произвольном порядке .
   1. Тип десериализован. Это создает блок, запускает его метод инициализации и смешивает расширения.
   2. Атрибуты десериализуются. Сюда входят свойства, которые могут применяться к любому блоку. Например: x, y, свернуто, отключено и данные.
   3. Дополнительное состояние десериализуется. Дополнительную информацию см. в документации по расширениям и мутаторам .
   4. Блок связан со своим родителем (если таковой существует).
   5. Иконки десериализованы. Отдельные значки десериализуются в произвольном порядке .
   6. Поля десериализованы. Отдельные поля десериализуются в произвольном порядке .
   7. Входные блоки десериализуются. Сюда входят блоки, подключенные к входным значениям и входным данным операторов. Отдельные входные данные десериализуются в произвольном порядке .
   8. Следующие блоки десериализуются.

Когда сохранять дополнительное состояние

Для блоков, если у вас есть что-то ниже в порядке, которое зависит от чего-то выше в порядке, вам следует продублировать эти данные и добавить их в свое дополнительное состояние.

Например, если у вас есть поле, которое существует только в том случае, если подключен следующий блок, вам следует добавить информацию об этом следующем блоке в свое дополнительное состояние, чтобы поле можно было добавить в ваш блок до того, как состояние поля будет десериализовано.

Однако если у вас есть ввод, который существует только в том случае, если поле имеет определенное значение, вам не нужно добавлять информацию о поле в дополнительное состояние. Это связано с тем, что сначала будет десериализовано состояние вашего поля, и когда это произойдет, вы сможете добавить входные данные в свой блок. Обычно добавление ввода инициируется валидатором .

Обратите внимание, что правило дублирования состояния также должно учитывать, что стеки блоков, значки, поля и входные блоки десериализуются в произвольном порядке. Например, если у вас есть одно поле B, которое существует только в том случае, если другое поле A имеет определенное значение, вам следует добавить информацию об A в дополнительное состояние на случай, если B будет десериализовано раньше A.

Блочные крючки

Сведения о том, как добавить дополнительную сериализацию к блокам, см. в документации по расширениям и мутаторам .

Полевые крючки

Сведения о том, как сериализовать поля, см. в документации по настраиваемым полям .

Хуки сериализатора

Система JSON позволяет регистрировать сериализаторы, которые сериализуют и десериализуют некоторое состояние. Встроенные сериализаторы Blockly заботятся о сериализации информации о блоках и переменных, но если вы хотите сериализовать другую информацию, вам нужно будет добавить свой собственный сериализатор. Например, комментарии на уровне рабочей области по умолчанию не сериализуются системой JSON. Если вы хотите их сериализовать, вам потребуется зарегистрировать дополнительный сериализатор.

Дополнительные сериализаторы часто используются для сериализации и десериализации состояния плагина.

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

Когда вы регистрируете сериализатор, вы должны предоставить несколько вещей:

• Имя сериализатора, под которым также сохраняются данные.
• Функция для save состояния плагина/системы, связанной с сериализатором.
• Функция clear состояния.
• Функция для load состояния.

• priority , который используется для определения порядка десериализации .

  Вы можете установить приоритет вашего сериализатора на основе встроенных приоритетов.

При вызове Blockly.serialization.workspaces.save будет вызвана функция save каждого сериализатора, и ее данные будут добавлены в окончательный вывод JSON:

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

При вызове Blockly.serialization.workspaces.load каждый сериализатор запускается в порядке приоритета. Сериализаторы с более положительными значениями приоритета запускаются раньше сериализаторов с менее положительными значениями приоритета.

При запуске сериализатора происходят две вещи:

1. Вызывается предоставленная функция clear . Это гарантирует, что состояние вашего плагина/системы будет чистым до загрузки нового состояния. Например, сериализатор комментариев рабочей области удалит все существующие комментарии из рабочей области.
2. Вызывается предоставленная функция load .

XML-система

Система XML позволяет сериализовать ваше рабочее пространство в узел XML. Это была оригинальная система сериализации Blockly. Сейчас он заморожен, а это значит, что он не получит новых функций. Поэтому мы рекомендуем по возможности использовать систему JSON.

Примечание. Информацию о том, как перейти на JSON, см. в руководстве по миграции .

API

Информацию об API-интерфейсах XML-системы см. в справочной документации .

Блочные крючки

Сведения о том, как добавить дополнительную сериализацию к блокам, см. в документации по расширениям и мутаторам .

Полевые крючки

Сведения о том, как сериализовать поля, см. в документации по настраиваемым полям .

Выбор между JSON и XML

Мы рекомендуем сериализатор JSON вместо XML. Система JSON позволяет сериализовать состояние вашего рабочего пространства в объект JavaScript. Это выгодно, потому что:

1. JSON легко сжать или преобразовать в другой формат.
2. С JSON легко работать программно.
3. JSON легко расширять и добавлять в него данные.

Кроме того, система XML больше не будет получать обновления, и ей уже не хватает функций по сравнению с сериализатором JSON. Например, вы можете зарегистрировать свой собственный сериализатор JSON, чтобы легко сохранять и загружать дополнительные данные, такие как данные для плагинов или добавленных вами настроек. Это невозможно в системе XML.

Если вы ранее использовали сериализацию XML, информацию о том, как выполнить обновление, см. в руководстве по миграции .