Chuyển đổi tuần tự

Quá trình chuyển đổi tuần tự sẽ lưu trạng thái không gian làm việc của bạn để có thể tải lại vào không gian làm việc sau. Điều này bao gồm việc chuyển đổi tuần tự trạng thái của mọi khối, biến hoặc trình bổ trợ mà bạn muốn lưu. Bạn có thể chuyển đổi tất cả dữ liệu cần lưu sang định dạng dựa trên văn bản để dễ dàng lưu trữ, sau đó tải lại dữ liệu đó vào không gian làm việc có đầy đủ chức năng sau này.

Blockly cung cấp 2 định dạng cho dữ liệu này: JSON và XML. Bạn nên sử dụng hệ thống JSON cho các dự án mới và khuyến khích các dự án cũ sử dụng XML để nâng cấp. Hệ thống XML là định dạng lưu cũ. Mô-đun này sẽ không bị xoá nhưng sẽ không nhận được các tính năng mới.

hệ thống JSON

Lưu ý: Để biết thông tin về cách chuyển từ XML sang JSON, hãy xem hướng dẫn di chuyển.

Hệ thống chuyển đổi tuần tự JSON bao gồm nhiều trình chuyển đổi tuần tự. Có sẵn các trình chuyển đổi tuần tự cho các khối và biến. Bạn cũng có thể đăng ký thêm các trình chuyển đổi tuần tự. Mỗi trình chuyển đổi tuần tự chịu trách nhiệm chuyển đổi tuần tự và giải trình tự trạng thái của một trình bổ trợ hoặc hệ thống cụ thể.

Đang lưu và tải

Không gian làm việc

Bạn có thể chuyển đổi tuần tự hoặc giải tuần tự trạng thái của toàn bộ không gian làm việc bằng cách gọi phương thức save và load trên không gian tên workspaces.

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

Những lệnh gọi này chuyển đổi tuần tự hoặc giải tuần tự hoá tất cả hệ thống riêng lẻ (do các trình chuyển đổi tuần tự biểu thị) đã được đăng ký với không gian làm việc.

Khối riêng lẻ

Bạn có thể chuyển đổi tuần tự hoặc giải tuần tự các khối riêng lẻ bằng cách gọi phương thức save và append trên không gian tên blocks.

const blockJson = Blockly.serialization.blocks.save(myBlock);
const duplicateBlock =
    Blockly.serialization.blocks.append(blockJson, myWorkspace);

Các hệ thống riêng lẻ

Bạn có thể chuyển đổi tuần tự hoặc giải tuần tự từng hệ thống (ví dụ: các khối, biến, trình bổ trợ, v.v.) bằng cách tạo trình chuyển đổi tuần tự liên kết và gọi các phương thức save và 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);

Thứ tự huỷ chuyển đổi tuần tự

Hệ thống JSON có thứ tự huỷ chuyển đổi tuần tự rõ ràng, giúp bạn dễ dàng ngăn chặn tình trạng trùng lặp trạng thái trong bản lưu.

Khi Blockly.serialization.workspaces.load được gọi, trình chuyển đổi tuần tự sẽ được cấp trạng thái để giải tuần tự theo thứ tự ưu tiên. Điều này được giải thích kỹ hơn trong phần Trình chuyển đổi tuần tự, và mục đích của trình chuyển đổi tuần tự là cho phép các trình chuyển đổi tuần tự phụ thuộc vào trạng thái của các hệ thống khác.

Thứ tự huỷ chuyển đổi tuần tự của các trình chuyển đổi tuần tự tích hợp sẵn là:

1. Biến được giải tuần tự.
2. Các quy tắc chặn được giải tuần tự. Từng ngăn xếp/khối cấp cao nhất sẽ được giải trình tự theo thứ tự tuỳ ý.
   1. Loại này được giải tuần tự. Thao tác này kích hoạt phương thức khởi tạo của khối, kết hợp các tiện ích, v.v.
   2. Các thuộc tính được giải trình tự. Quy định này bao gồm các thuộc tính có thể áp dụng cho khối bất kỳ. Ví dụ: x, y, đã thu gọn, đã tắt, dữ liệu, v.v.
   3. Trạng thái bổ sung được giải tuần tự. Vui lòng xem tài liệu về Tiện ích và bộ biến đổi để biết thêm thông tin.
   4. Khối được kết nối với thành phần mẹ (nếu có).
   5. Các biểu tượng được giải trình tự. Các biểu tượng riêng lẻ được giải trình tự theo thứ tự tuỳ ý.
   6. Các trường được giải tuần tự. Các trường riêng lẻ được giải trình tự theo thứ tự tuỳ ý.
   7. Các khối đầu vào được giải tuần tự. Bao gồm cả các khối kết nối với đầu vào giá trị và đầu vào câu lệnh. Các dữ liệu đầu vào riêng lẻ được giải trình tự theo thứ tự tuỳ ý.
   8. Các khối tiếp theo được giải trình tự.

Thời điểm lưu trạng thái bổ sung

Đối với các khối, nếu có thứ tự thấp hơn và phụ thuộc vào thứ tự cao hơn trong thứ tự, bạn nên sao chép dữ liệu đó và thêm dữ liệu đó vào trạng thái bổ sung.

Ví dụ: nếu bạn có một trường chỉ tồn tại khi một khối tiếp theo được kết nối, bạn nên thêm thông tin về khối tiếp theo đó vào trạng thái bổ sung để có thể thêm trường vào khối trước khi giải trình tự trạng thái của trường.

Tuy nhiên, nếu có một dữ liệu đầu vào chỉ tồn tại nếu một trường có một giá trị nhất định, thì bạn không cần thêm thông tin về trường đó vào trạng thái bổ sung. Nguyên nhân là do trạng thái của trường sẽ được giải trình tự trước tiên và khi trạng thái đó xuất hiện, bạn có thể thêm dữ liệu đầu vào vào khối của mình. Thông thường, việc thêm dữ liệu đầu vào sẽ được validator kích hoạt.

Xin lưu ý rằng quy tắc về sao chép trạng thái cũng cần tính đến việc giải trình tự các ngăn xếp khối, biểu tượng, trường và khối đầu vào được giải trình tự theo thứ tự tuỳ ý. Ví dụ: nếu bạn có một trường B chỉ tồn tại nếu một trường khác A có giá trị nhất định, thì bạn nên thêm thông tin về A vào trạng thái bổ sung của mình trong trường hợp B được giải tuần tự trước A.

Móc dạng khối

Để biết thông tin về cách thêm quy trình chuyển đổi tuần tự bổ sung vào các khối, hãy xem tài liệu về Tiện ích và bộ thay đổi.

Mạo trường

Để biết thông tin về cách chuyển đổi tuần tự các trường, hãy xem tài liệu về Trường tuỳ chỉnh.

Hook của bộ chuyển đổi tuần tự

Hệ thống JSON cho phép bạn đăng ký các trình chuyển đổi tuần tự để chuyển đổi tuần tự và giải tuần tự một số trạng thái. Các trình chuyển đổi tuần tự tích hợp của Blockly đảm nhiệm việc chuyển đổi tuần tự thông tin về các khối và biến. Tuy nhiên, nếu muốn chuyển đổi tuần tự thông tin khác, bạn cần thêm trình chuyển đổi tuần tự của riêng mình. Ví dụ: theo mặc định, hệ thống JSON không chuyển đổi tuần tự các nhận xét ở cấp không gian làm việc. Nếu muốn chuyển đổi tuần tự các phiên bản này, bạn cần đăng ký thêm một trình chuyển đổi tuần tự.

Các trình chuyển đổi tuần tự bổ sung thường được dùng để chuyển đổi tuần tự và giải tuần tự trạng thái của trình bổ trợ.

Blockly.serialization.registry.register(
    'workspace-comments',  // Name
    {
      save: saveFn,      // Save function
      load: loadFn,      // Load function
      clear: clearFn,    // Clear function
      priority: 10,      // Priority
    });

Khi đăng ký một trình chuyển đổi tuần tự, bạn phải cung cấp một số thông tin sau:

• Tên của trình chuyển đổi tuần tự mà dữ liệu cũng được lưu trong đó.
• Một hàm để save trạng thái của trình bổ trợ/hệ thống liên kết với trình chuyển đổi tuần tự.
• Một hàm để clear trạng thái.
• Một hàm để load trạng thái.

• priority, dùng để xác định thứ tự huỷ chuyển đổi tuần tự.

  Bạn có thể căn cứ mức độ ưu tiên của trình chuyển đổi tuần tự dựa trên các mức ưu tiên tích hợp sẵn

Khi Blockly.serialization.workspaces.save được gọi, từng hàm save của trình chuyển đổi tuần tự sẽ được gọi và dữ liệu của hàm đó sẽ được thêm vào dữ liệu đầu ra JSON cuối cùng:

{
  "blocks": { ... },
  "workspaceComments": [ // Provided by workspace-comments serializer
    {
      "x": 239,
      "y": 31,
      "text": "Add 2 + 2"
    },
    // etc...
  ]
}

Khi Blockly.serialization.workspaces.load được gọi, mỗi trình chuyển đổi tuần tự sẽ được kích hoạt theo thứ tự ưu tiên. Các trình chuyển đổi tuần tự có giá trị ưu tiên dương hơn sẽ được kích hoạt trước các trình chuyển đổi tuần tự có giá trị ưu tiên thấp hơn.

Khi trình chuyển đổi tuần tự được kích hoạt, có hai điều sẽ xảy ra:

1. Hàm clear đã cho được gọi. Việc này đảm bảo trạng thái của trình bổ trợ/hệ thống sạch trước khi tải thêm trạng thái. Ví dụ: trình chuyển đổi tuần tự-nhận xét trong workspace sẽ xoá tất cả nhận xét hiện có khỏi không gian làm việc.
2. Hàm load đã cho được gọi.

Hệ thống XML

Hệ thống XML cho phép bạn chuyển đổi tuần tự không gian làm việc của mình thành nút XML. Đây là hệ thống chuyển đổi tuần tự ban đầu của Blockly. Hiện ứng dụng này đã được đóng gói thành băng, điều này có nghĩa là nó sẽ không nhận được tính năng mới. Do đó, bạn nên sử dụng hệ thống JSON nếu có thể.

Lưu ý: Để biết thông tin về cách di chuyển sang JSON, hãy xem hướng dẫn di chuyển.

API

Để biết thông tin về các API của hệ thống XML, vui lòng xem tài liệu tham khảo.

Móc dạng khối

Để biết thông tin về cách thêm quy trình chuyển đổi tuần tự bổ sung vào các khối, hãy xem tài liệu về Tiện ích và bộ thay đổi.

Mạo trường

Để biết thông tin về cách chuyển đổi tuần tự các trường, hãy xem tài liệu về Trường tuỳ chỉnh.

Chọn giữa JSON và XML

Bạn nên sử dụng trình chuyển đổi tuần tự JSON thay vì XML. Hệ thống JSON cho phép bạn chuyển đổi tuần tự trạng thái không gian làm việc thành đối tượng JavaScript. Điều này là bất lợi vì:

1. Định dạng JSON rất dễ nén hoặc chuyển đổi sang một định dạng khác.
2. JSON dễ làm việc theo phương thức lập trình.
3. JSON dễ mở rộng và thêm dữ liệu.

Ngoài ra, hệ thống XML sẽ không còn nhận được bản cập nhật và thiếu các tính năng so với trình chuyển đổi tuần tự JSON. Ví dụ: bạn có thể đăng ký trình chuyển đổi tuần tự JSON của riêng mình để dễ dàng lưu và tải thêm dữ liệu, chẳng hạn như dữ liệu cho các trình bổ trợ hoặc các yếu tố tuỳ chỉnh mà bạn đã thêm. Điều này không được hỗ trợ trong hệ thống XML.

Nếu bạn đã từng sử dụng tính năng chuyển đổi tuần tự XML, hãy xem hướng dẫn di chuyển để biết thông tin về cách nâng cấp.