序列化

序列化作業會儲存工作區的狀態，方便稍後載入至工作區。這包括針對您要儲存的任何區塊、變數或外掛程式將狀態序列化。您可以將所有需要儲存的資料轉換成文字格式以輕鬆儲存，然後再將資料載入回功能完善的工作區。

Blockly 提供兩種格式的資料：JSON 和 XML。我們建議使用 JSON 系統建立新專案，並建議採用 XML 的舊版專案進行升級。XML 系統是舊版的儲存格式。系統不會移除 GCC，但將無法收到新功能。

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. 後續區塊會反序列化。

何時適合儲存額外狀態

如果區塊順序較低，且其順序取決於較高項目，則應複製該項資料，並將其新增至額外狀態。

舉例來說，如果您的欄位只有在連線下一個區塊時才存在，則應將下一個區塊的相關資訊新增至額外狀態，這樣該欄位可在欄位狀態去識別化之前，新增至區塊。

不過，如果輸入只有在欄位具有特定值時才存在，就不需要將欄位相關資訊新增至額外狀態。這是因為欄位的狀態會先去序列化，接著，您可以將輸入內容新增至區塊。新增的輸入內容通常是由validator觸發。

請注意，複製狀態的規則也應考量，區塊堆疊、圖示、欄位和輸入區塊會按任意順序反序列化。舉例來說，如果某個欄位 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 函式。這樣可確保系統先清除外掛程式/系統狀態，再載入更多狀態。例如，workspace-comments serializer 會移除工作區中所有現有的註解。
  2. 系統會呼叫提供的 load 函式。

XML 系統

XML 系統可讓您將工作區序列化為 XML 節點。這是 Blockly 的原始序列化系統。目前已經經過冰箱 因此無法取得新功能因此，我們建議盡可能使用 JSON 系統。

API

如需 XML 系統 API 的相關資訊，請參閱參考說明文件。

區塊掛鉤

如要瞭解如何將額外的序列化作業新增至區塊，請參閱「擴充功能和變動」說明文件。

球場掛勾

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

選擇 JSON 或 XML

建議您使用 JSON 序列化程式，而非 XML。JSON 系統可讓您將工作區的狀態序列化為 JavaScript 物件。優點如下：

  1. JSON 很容易壓縮或轉換為其他格式。
  2. JSON 適合搭配程式使用。
  3. JSON 可讓您輕鬆擴充及附加資料。

此外，XML 系統不會再接收更新，且已取得其與 JSON 序列化程式相比較的功能。舉例來說，您可以註冊自己的 JSON 序列化程式，即可輕鬆儲存及載入其他資料，例如您新增的外掛程式或自訂項目資料。XML 系統則無法這麼做。

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