Сохранить и загрузить

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

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

JSON-система

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

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

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

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

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

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

Крючки для блоков

Информацию о том, как добавить дополнительную сериализацию к блокам, см. в документации Mutators .

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

Информацию о сериализации полей см. в документации по пользовательским полям .

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

Система 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 . Это гарантирует, что состояние вашего плагина/системы будет чистым перед загрузкой следующего состояния. Например, сериализатор workspace-comments удалит все существующие комментарии из workspace.
  2. Вызывается предоставленная функция load .

XML-система

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

API-интерфейсы

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

Крючки для блоков

Информацию о том, как добавить дополнительную сериализацию к блокам, см. в документации Mutators .

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

Информацию о сериализации полей см. в документации по пользовательским полям .

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

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

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

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

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