儲存並載入

序列化會儲存工作區的狀態，方便日後載入工作區。這包括序列化您要儲存的任何區塊、變數或外掛程式的狀態。您可以將所有需要儲存的資料轉換為文字格式，方便儲存，然後稍後將這些資料載入功能完整的工作區。

Blockly 提供兩種格式供您使用：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. 程序模型會經過序列化。
  3. 區塊會經過反序列化。個別頂層區塊會以任意順序進行反序列化。
    1. 類型已經過反序列化。這會建構區塊、觸發其初始化方法，並混合擴充功能。
    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 函式。這可確保在載入更多狀態之前，外掛程式/系統的狀態是乾淨的。舉例來說，工作區留言序列化器會從工作區移除所有現有的留言。
  2. 系統會呼叫提供的 load 函式。

XML 系統

XML 系統可讓您將工作區序列化為 XML 節點。這是 Blockly 的原始序列化系統。此版本已停止更新，也就是說不會再新增新功能。因此，建議您盡可能使用 JSON 系統。

API

如要瞭解 XML 系統的 API，請參閱參考說明文件。

封鎖掛鉤

如要瞭解如何在區塊中新增額外的序列化，請參閱 Mutators 說明文件。

欄位掛鉤

如要瞭解如何序列化欄位，請參閱「自訂欄位」說明文件。

選擇 JSON 或 XML

我們建議您使用 JSON 序列化器，而非 XML。JSON 系統可讓您將工作區狀態序列化為 JavaScript 物件。這麼做有助於：

  1. JSON 很容易壓縮或轉換為其他格式。
  2. JSON 很容易透過程式碼處理。
  3. JSON 很容易擴充及附加資料。

此外，XML 系統將不再接收更新，且相較於 JSON 序列化器，它缺乏許多功能。舉例來說，您可以註冊自己的 JSON 序列化器，輕鬆儲存及載入其他資料，例如您新增的外掛程式或自訂項目的資料。但 XML 系統無法做到這一點。

如果您先前使用 XML 序列化，請參閱遷移指南，瞭解如何升級。