Trong tài liệu này, chúng ta sẽ thảo luận về cách sử dụng JSON để xác định các đầu vào, trường (bao gồm cả nhãn) và mối kết nối trong khối của bạn. Nếu bạn chưa quen với các thuật ngữ này, hãy xem phần Cấu trúc của một khối trước khi tiếp tục.
Bạn cũng có thể xác định các đầu vào, trường và kết nối trong JavaScript.
Tổng quan
Trong JSON, bạn mô tả cấu trúc của một khối bằng một hoặc nhiều chuỗi thông báo (message0, message1, ...) và các mảng đối số tương ứng (args0, args1, ...). Chuỗi thông báo bao gồm văn bản (được chuyển đổi thành nhãn) và mã thông báo nội suy (%1, %2, ...), đánh dấu vị trí của các kết nối và trường không phải nhãn. Các mảng đối số mô tả cách xử lý mã thông báo nội suy.
Ví dụ: khối này:
được xác định bằng JSON sau:
JSON
{
"message0": "set %1 to %2",
"args0": [
{
"type": "field_variable",
"name": "VAR",
"variable": "item",
"variableTypes": [""]
},
{
"type": "input_value",
"name": "VALUE"
}
]
}
Mã thông báo nội suy đầu tiên (%1) biểu thị một trường biến (type: "field_variable"). Mã thông báo này được mô tả bằng đối tượng đầu tiên trong mảng args0. Mã thông báo thứ hai (%2) biểu thị mối kết nối đầu vào ở cuối đầu vào giá trị (type: "input_value"). Mã thông báo này được mô tả bằng đối tượng thứ hai trong mảng args0.
Tin nhắn và phương thức nhập
Khi một mã thông báo nội suy đánh dấu một kết nối, mã thông báo đó thực sự đánh dấu điểm cuối của đầu vào chứa kết nối. Điều này là do các kết nối trong giá trị và câu lệnh đầu vào được hiển thị ở cuối đầu vào. Đầu vào chứa tất cả các trường (bao gồm cả nhãn) sau đầu vào trước đó và cho đến mã thông báo hiện tại. Các phần sau đây cho thấy các thông báo mẫu và dữ liệu đầu vào được tạo từ các thông báo đó.
Ví dụ 1
JSON
{
"message0": "set %1 to %2",
"args0": [
{"type": "field_variable", ...} // token %1
{"type": "input_value", ...} // token %2
],
}
Thao tác này sẽ tạo một đầu vào có giá trị duy nhất với 3 trường: một nhãn ("set"), một trường biến và một nhãn khác ("to").
Ví dụ 2
JSON
{
"message0": "%1 + %2",
"args0": [
{"type": "input_value", ...} // token %1
{"type": "input_value", ...} // token %2
],
}
Thao tác này sẽ tạo ra 2 giá trị đầu vào. Danh sách đầu tiên không có trường nào, còn danh sách thứ hai có một trường ("+").
Ví dụ 3
JSON
{
"message0": "%1 + %2 %3",
"args0": [
{"type": "input_value", ...} // token %1
{"type": "input_end_row", ...} // token %2
{"type": "input_value", ...} // token %3
],
}
Thao tác này sẽ tạo ra:
- Giá trị đầu vào không có trường,
- Một đầu vào cuối hàng có trường nhãn (
"+"), khiến đầu vào giá trị sau đây được hiển thị trên một hàng mới và - Giá trị đầu vào không có trường.
Đầu vào giả ở cuối thông báo
Nếu chuỗi message của bạn kết thúc bằng văn bản hoặc các trường, bạn không cần thêm mã thông báo nội suy cho đầu vào giả chứa các chuỗi đó – Blockly sẽ thêm mã thông báo đó cho bạn. Ví dụ: thay vì xác định một khối lists_isEmpty như sau:
JSON
{
"message0": "%1 is empty %2",
"args0": [
{"type": "input_value", ...} // token %1
{"type": "input_dummy", ...} // token %2
],
}
bạn có thể cho phép Blockly thêm đầu vào giả và xác định đầu vào đó như sau:
JSON
{
"message0": "%1 is empty",
"args0": [
{"type": "input_value", ...} // token %1
],
}
Việc tự động thêm một đầu vào giả ở cuối cho phép người dịch thay đổi message mà không cần sửa đổi các đối số mô tả mã thông báo nội suy. Để biết thêm thông tin, hãy xem phần Thứ tự mã thông báo nội suy.
implicitAlign
Trong một số ít trường hợp, đầu vào giả ở cuối được tạo tự động cần được căn chỉnh với "RIGHT" hoặc "CENTRE". Giá trị mặc định nếu không được chỉ định là "LEFT".
Trong ví dụ bên dưới, message0 là "send email to %1 subject %2 secure %3" và Blockly sẽ tự động thêm một dữ liệu đầu vào giả cho hàng thứ ba. Việc đặt implicitAlign0 thành "RIGHT" sẽ buộc hàng này phải được căn chỉnh sang phải.
implicitAlign áp dụng cho tất cả các đầu vào không được xác định rõ ràng trong định nghĩa khối JSON, bao gồm cả đầu vào cuối hàng thay thế các ký tự dòng mới ('\n'). Ngoài ra, còn có thuộc tính không dùng nữa lastDummyAlign0 có hành vi tương tự như implicitAlign0.
Khi thiết kế các khối cho RTL (tiếng Ả Rập và tiếng Do Thái), trái và phải sẽ bị đảo ngược.
Do đó, "RIGHT" sẽ căn chỉnh các trường sang bên trái.
Nhiều tin nhắn
Một số khối được chia thành hai hoặc nhiều phần riêng biệt. Hãy xem xét khối lặp lại này có 2 hàng:
Nếu khối này được mô tả bằng một thông báo duy nhất, thì thuộc tính message0 sẽ là "repeat %1 times %2 do %3", trong đó %2 biểu thị một đầu vào cuối hàng. Chuỗi này gây khó khăn cho người dịch vì rất khó giải thích ý nghĩa của phép thay thế %2. Thậm chí, người dùng có thể không muốn sử dụng đầu vào %2 cuối hàng trong một số ngôn ngữ. Và có thể có nhiều khối muốn chia sẻ văn bản của hàng thứ hai. Cách tiếp cận tốt hơn là sử dụng nhiều thuộc tính message và args:
JSON
{
"message0": "repeat %1 times",
"args0": [
{"type": "input_value", ...} // token %1 in message0
],
"message1": "do %1",
"args1": [
{"type": "input_statement", ...} // token %1 in message1
],
}
Bạn có thể xác định bất kỳ số lượng thuộc tính message, args và implicitAlign nào ở định dạng JSON, bắt đầu từ 0 và tăng tuần tự. Xin lưu ý rằng Block Factory không thể chia thông báo thành nhiều phần, nhưng bạn có thể dễ dàng thực hiện việc này theo cách thủ công.
Thứ tự mã thông báo nội suy
Khi bản địa hoá các khối, bạn có thể cần thay đổi thứ tự của các mã thông báo nội suy trong một thông báo. Điều này đặc biệt quan trọng đối với những ngôn ngữ có thứ tự từ khác với tiếng Anh. Ví dụ: chúng ta bắt đầu bằng một khối do thông báo "set %1 to %2" xác định:
Bây giờ, hãy xem xét một ngôn ngữ giả định mà trong đó "set %1 to %2" cần được đảo ngược thành "put %2 in %1". Việc thay đổi thông báo (bao gồm cả thứ tự của các mã thông báo nội suy) và giữ nguyên mảng đối số sẽ dẫn đến khối sau:
Blockly tự động thay đổi thứ tự của các trường, tạo một đầu vào giả và chuyển từ đầu vào bên ngoài sang đầu vào bên trong.
Khả năng thay đổi thứ tự của các mã thông báo nội suy trong một thông báo giúp việc bản địa hoá trở nên dễ dàng hơn. Để biết thêm thông tin, hãy xem phần Nội suy thông báo JSON.
Xử lý văn bản
Văn bản ở hai bên mã thông báo nội suy sẽ bị cắt bỏ khoảng trắng.
Văn bản sử dụng ký tự % (ví dụ: khi đề cập đến tỷ lệ phần trăm) phải sử dụng %% để không được diễn giải là mã thông báo nội suy.
Blockly cũng tự động thay thế mọi ký tự dòng mới (\n) trong chuỗi thông báo bằng một đầu vào cuối hàng.
JSON
{
"message0": "set %1\nto %2",
"args0": [
{"type": "field_variable", ...}, // token %1
{"type": "input_value", ...}, // token %2
]
}
Mảng đối số
Mỗi chuỗi thông báo được ghép nối với một mảng args có cùng số lượng. Ví dụ: message0 đi kèm với args0. Các mã thông báo nội suy (%1, %2, ...) đề cập đến các mục của mảng args và phải hoàn toàn khớp với mảng args0: không có mục nào trùng lặp, không có mục nào bị bỏ sót. Số hiệu mã thông báo đề cập đến thứ tự của các mục trong mảng đối số; bạn không bắt buộc phải sắp xếp theo thứ tự trong chuỗi thông báo.
Mỗi đối tượng trong mảng đối số đều có một chuỗi type. Các tham số còn lại sẽ khác nhau tuỳ thuộc vào loại:
Bạn cũng có thể xác định các trường tuỳ chỉnh và đầu vào tuỳ chỉnh của riêng mình, rồi truyền chúng dưới dạng đối số.
các trường thay thế
Mỗi đối tượng cũng có thể có một trường alt. Trong trường hợp Blockly không nhận dạng được type của đối tượng, thì đối tượng alt sẽ được dùng thay thế. Ví dụ: nếu một trường mới có tên là field_time được thêm vào Blockly, thì các khối sử dụng trường này có thể dùng alt để xác định một phương án dự phòng field_input cho các phiên bản cũ của Blockly:
JSON
{
"message0": "sound alarm at %1",
"args0": [
{
"type": "field_time",
"name": "TEMPO",
"hour": 9,
"minutes": 0,
"alt":
{
"type": "field_input",
"name": "TEMPOTEXT",
"text": "9:00"
}
}
]
}
Đối tượng alt có thể có đối tượng alt riêng, do đó cho phép liên kết.
Cuối cùng, nếu không tạo được một đối tượng trong mảng args0 (sau khi thử mọi đối tượng alt), thì Blockly sẽ bỏ qua đối tượng đó.