シリアル化

シリアル化は、ワークスペースの状態を保存して、後でワークスペースに読み込めるようにします。これには、保存するブロック、変数、プラグインの状態のシリアル化も含まれます。保存しておく必要があるすべてのデータは、テキストベースの形式に変換して簡単に保存でき、後で完全に機能するワークスペースに読み込めます。

Blockly は、このデータに 2 つの形式（JSON と XML）を提供します。新しいプロジェクトには JSON システムを使用することをおすすめします。XML を使用して古いプロジェクトをアップグレードすることをおすすめします。XML システムは従来の保存形式です。削除されることはありませんが、新機能は提供されません。

JSON システム

JSON シリアル化システムは、複数のシリアライザで構成されています。ブロックと変数用のシリアライザが組み込まれています。追加のシリアライザーを登録することもできます。各シリアライザは、特定のプラグインまたはシステムの状態をシリアル化およびシリアル化解除します。

保存と読み込み

ワークスペース

workspaces 名前空間で save メソッドと load メソッドを呼び出すと、ワークスペース全体の状態をシリアル化または逆シリアル化できます。

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

これらの呼び出しは、ワークスペースに登録されている個々のシステム（シリアライザによって表される）をすべてシリアル化または逆シリアル化します。

個別のブロック

blocks 名前空間で save メソッドと append メソッドを呼び出して、個々のブロックをシリアル化または逆シリアル化できます。

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. ブロックはシリアル化解除される。個々のスタックまたはトップレベルのブロックは、任意の順序でシリアル化解除されます。
    1. 型が逆シリアル化されている。これにより、ブロックの init メソッドがトリガーされたり、拡張機能が組み合わされたりします。
    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 が呼び出されると、各シリアライザは優先度の高い順にトリガーされます。優先度の値が正のシリアライザは、優先度の値が小さいシリアライザより先にトリガーされます。

シリアライザがトリガーされると、次の 2 つのことが行われます。

  1. 指定された clear 関数が呼び出されます。これにより、さらに状態が読み込まれる前にプラグインやシステムの状態がクリーンになります。たとえば、workspace-comments シリアライザは、ワークスペースから既存のコメントをすべて削除します。
  2. 指定された load 関数が呼び出されます。

XML システム

XML システムを使用すると、ワークスペースを XML ノードにシリアル化できます。これは Blockly の元のシリアル化システムです。現在はアイスボックス化されているため、新機能は提供されません。そのため、可能であれば JSON システムを使用することをおすすめします。

API

XML システムの API については、リファレンス ドキュメントをご覧ください。

ブロックフック

ブロックに別のシリアル化を追加する方法については、拡張機能とミューテータのドキュメントをご覧ください。

フィールド フック

フィールドをシリアル化する方法については、カスタム フィールドのドキュメントをご覧ください。

JSON と XML の選択

XML よりも JSON シリアライザをおすすめします。JSON システムでは、ワークスペースの状態を JavaScript オブジェクトにシリアル化できます。これには次の利点があります。

  1. JSON は簡単に圧縮したり、別の形式に変換したりできます。
  2. JSON をプログラムで操作するのは簡単です。
  3. JSON はデータの拡張と追加を簡単に行えます。

また、XML システムは更新を受信できなくなり、JSON シリアライザと比較してすでに機能が不足しています。たとえば、独自の JSON シリアライザを登録することで、プラグインやカスタマイズなどの追加データを簡単に保存および読み込むことができます。これは、XML システムでは行えません。

以前に XML シリアル化を使用したことがある場合は、アップグレード方法について移行ガイドをご覧ください。