調査アンケート: Blockly のご利用体験についてお聞かせください

このページは Cloud Translation API によって翻訳されました。

シリアル化

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

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

JSON システム

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

保存と読み込み

ワークスペース

ワークスペース全体の状態をシリアル化またはシリアル化解除するには、workspaces Namespace で save メソッドと load メソッドを呼び出します。

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

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

個々のブロック

個々のブロックをシリアル化またはシリアル化解除するには、blocks Namespace で 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. 型が逆シリアル化されます。これにより、ブロックが構築され、init メソッドがトリガーされ、拡張機能が混在します。
2. 属性が逆シリアル化されます。これには、任意のブロックに適用できるプロパティが含まれます。たとえば、x、y、collapsed、disabled、data などです。
3. 余分な状態が逆シリアル化されます。詳細については、拡張機能とミュータタのドキュメントをご覧ください。
4. ブロックが親に接続されます（存在する場合）。
5. アイコンがシリアル化解除されています。個々のアイコンは任意の順序でシリアル化解除されます。
6. フィールドが逆シリアル化されます。個々のフィールドは任意の順序で逆シリアル化されます。
7. 入力ブロックがシリアル化解除されます。これには、値入力とステートメント入力に接続されているブロックが含まれます。個々の入力は任意の順序で逆シリアル化されます。
8. 次のブロックが逆シリアル化されます。

追加の状態を保存するタイミング

ブロックの場合、順序が後ろにあるものが順序が前にあるものに依存している場合は、そのデータを複製して追加の状態に追加する必要があります。

たとえば、次のブロックが接続されている場合にのみ存在するフィールドがある場合は、その次のブロックに関する情報を追加の状態に追加する必要があります。これにより、フィールドの状態が逆シリアル化される前に、フィールドをブロックに追加できます。

ただし、フィールドに特定の値がある場合にのみ存在する入力がある場合は、フィールドに関する情報をその他の状態に追加する必要はありません。これは、フィールドの状態が最初に逆シリアル化され、その状態になったときに入力をブロックに追加できるためです。通常、入力の追加はバリデータによってトリガーされます。

状態の重複に関するルールでは、ブロックスタック、アイコン、フィールド、入力ブロックが任意の順序で逆シリアル化されることも考慮する必要があります。たとえば、別のフィールド A に特定の値が存在する場合にのみ存在するフィールド B がある場合、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 つの処理が行われます。

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

XML システム

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

API

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

ブロックフック

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

フィールドフック

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

JSON または XML の選択

XML よりも JSON シリアライザを使用することをおすすめします。JSON システムを使用すると、ワークスペースの状態を JavaScript オブジェクトにシリアル化できます。メリットは次のとおりです。

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

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

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