Struktur blok dalam JSON

Dalam dokumen ini, kita akan membahas cara menggunakan JSON untuk menentukan input, kolom (termasuk label), dan koneksi di blok Anda. Jika Anda belum memahami istilah-istilah ini, lihat Anatomi blok sebelum melanjutkan.

Anda juga dapat menentukan input, kolom, dan koneksi di JavaScript.

Ringkasan

Dalam JSON, Anda menjelaskan struktur blok dengan satu atau beberapa string pesan (message0, message1, ...) dan array argumen yang sesuai (args0, args1, ...). String pesan terdiri dari teks, yang dikonversi menjadi label, dan token interpolasi (%1, %2, ...), yang menandai lokasi koneksi dan kolom non-label. Array argumen menjelaskan cara menangani token interpolasi.

Misalnya, blok ini:

Blok setter variabel. Elemen ini memiliki label "set", dropdown untuk memilih variabel, label "to", dan input nilai.

ditentukan oleh JSON berikut:

JSON

{
  "message0": "set %1 to %2",
  "args0": [
    {
      "type": "field_variable",
      "name": "VAR",
      "variable": "item",
      "variableTypes": [""]
    },
    {
      "type": "input_value",
      "name": "VALUE"
    }
  ]
}

Token interpolasi pertama (%1) merepresentasikan kolom variabel (type: "field_variable"). Kolom ini dijelaskan oleh objek pertama dalam array args0. Token kedua (%2) merepresentasikan koneksi input di akhir input nilai (type: "input_value"). Token ini dijelaskan oleh objek kedua dalam array args0.

Pesan dan input

Saat menandai koneksi, token interpolasi sebenarnya menandai akhir input yang berisi koneksi. Hal ini karena koneksi dalam input nilai dan pernyataan dirender di akhir input. Input berisi semua kolom (termasuk label) setelah input sebelumnya dan hingga token saat ini. Bagian berikut menunjukkan contoh pesan dan input yang dibuat dari pesan tersebut.

Contoh 1

JSON

{
  "message0": "set %1 to %2",
  "args0": [
    {"type": "field_variable", ...} // token %1
    {"type": "input_value", ...}    // token %2
  ],
}

Tindakan ini akan membuat input nilai tunggal dengan tiga kolom: label ("set"), kolom variabel, dan label lainnya ("to").

Petakan pesan "set %1 to %2" ke input nilai dengan tiga kolom.

Contoh 2

JSON

{
  "message0": "%1 + %2",
  "args0": [
    {"type": "input_value", ...} // token %1
    {"type": "input_value", ...} // token %2
  ],
}

Tindakan ini akan membuat dua input nilai. Yang pertama tidak memiliki kolom dan yang kedua memiliki satu kolom ("+").

Petakan pesan "%1 + %2" ke dua input nilai.

Contoh 3

JSON

{
  "message0": "%1 + %2 %3",
  "args0": [
    {"type": "input_value", ...}   // token %1
    {"type": "input_end_row", ...} // token %2
    {"type": "input_value", ...}   // token %3
  ],
}

Tindakan ini akan membuat:

  • Input nilai tanpa kolom,
  • Input akhir baris dengan kolom label ("+"), yang menyebabkan input nilai berikutnya dirender pada baris baru, dan
  • Input nilai tanpa kolom.

Petakan pesan "%1 + %2 %3" ke dua input nilai dan input akhir baris.

Input dummy di akhir pesan

Jika string message Anda diakhiri dengan teks atau kolom, Anda tidak perlu menambahkan token interpolasi untuk input dummy yang memuatnya -- Blockly akan menambahkannya untuk Anda. Misalnya, daripada menentukan blok lists_isEmpty seperti ini:

JSON

{
  "message0": "%1 is empty %2",
  "args0": [
    {"type": "input_value", ...} // token %1
    {"type": "input_dummy", ...} // token %2
  ],
}

Petakan pesan "%1 kosong" ke input nilai dan input dummy yang dibuat secara otomatis.

Anda dapat membiarkan Blockly menambahkan input dummy dan menentukannya seperti ini:

JSON

{
  "message0": "%1 is empty",
  "args0": [
    {"type": "input_value", ...} // token %1
  ],
}

Petakan pesan "%1 kosong" ke input nilai dan input dummy yang dibuat secara otomatis.

Penambahan otomatis input dummy di akhir memungkinkan penerjemah mengubah message tanpa perlu mengubah argumen yang menjelaskan token interpolasi. Untuk mengetahui informasi selengkapnya, lihat Urutan token interpolasi.

implicitAlign

Dalam kasus yang jarang terjadi, input dummy di akhir yang dibuat secara otomatis harus disejajarkan dengan "RIGHT" atau "CENTRE". Default jika tidak ditentukan adalah "LEFT".

Dalam contoh di bawah, message0 adalah "send email to %1 subject %2 secure %3" dan Blockly otomatis menambahkan input dummy untuk baris ketiga. Menetapkan implicitAlign0 ke "RIGHT" akan memaksa baris ini diratakan ke kanan.

Pemblokiran untuk mengirim email. Baris pertama memiliki label "kirim email ke" dan input nilai. Baris kedua memiliki label "subject" dan input nilai. Baris ketiga memiliki label "secure" dan kotak centang; baris ini rata kanan.

implicitAlign berlaku untuk semua input yang tidak ditentukan secara eksplisit dalam definisi blok JSON, termasuk input akhir baris yang menggantikan karakter newline ('\n'). Ada juga properti yang tidak digunakan lagi lastDummyAlign0 yang memiliki perilaku yang sama dengan implicitAlign0.

Saat mendesain blok untuk RTL (Arab dan Ibrani), kiri dan kanan dibalik. Dengan demikian, "RIGHT" akan menyelaraskan kolom ke kiri.

Beberapa pesan

Beberapa blok secara alami dibagi menjadi dua atau lebih bagian terpisah. Pertimbangkan blok pengulangan ini yang memiliki dua baris:

Blok berulang dengan dua baris. Baris pertama memiliki label "repeat", input nilai, dan label "times". Baris kedua memiliki label "lakukan" dan input pernyataan.

Jika blok ini dijelaskan dengan satu pesan, properti message0 akan menjadi "repeat %1 times %2 do %3", dengan %2 merepresentasikan input akhir baris. String ini sulit diterjemahkan karena sulit untuk menjelaskan arti penggantian %2. Input %2akhir baris mungkin juga tidak diinginkan dalam beberapa bahasa. Mungkin ada beberapa blok yang ingin membagikan teks baris kedua. Pendekatan yang lebih baik adalah menggunakan lebih dari satu properti message dan 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
  ],
}

Petakan pesan "repeat %1 times" ke input nilai dan input dummy yang dibuat secara otomatis, serta pesan "do %1" ke input pernyataan.

Sejumlah properti message, args, dan implicitAlign dapat ditentukan dalam format JSON, dimulai dengan 0 dan diurutkan secara berurutan. Perhatikan bahwa Block Factory tidak dapat membagi pesan menjadi beberapa bagian, tetapi Anda dapat melakukannya secara manual dengan mudah.

Urutan token interpolasi

Saat melokalkan blok, Anda mungkin perlu mengubah urutan token interpolasi dalam pesan. Hal ini sangat penting dalam bahasa yang memiliki urutan kata yang berbeda dengan bahasa Inggris. Misalnya, kita mulai dengan blok yang ditentukan oleh pesan "set %1 to %2":

Blok setter variabel dengan label "set", kolom dropdown untuk variabel, label "to", dan input nilai eksternal.

Sekarang pertimbangkan bahasa hipotetis di mana "set %1 to %2" perlu dibalik untuk mengatakan "put %2 in %1". Mengubah pesan (termasuk urutan token interpolasi) dan membiarkan array argumen tidak berubah akan menghasilkan blok berikut:

Blok setter variabel dengan label "put", input nilai inline, label "to", dan kolom dropdown untuk variabel.

Blockly otomatis mengubah urutan kolom, membuat input dummy, dan beralih dari input eksternal ke internal.

Kemampuan untuk mengubah urutan token interpolasi dalam pesan mempermudah pelokalan. Untuk mengetahui informasi selengkapnya, lihat interpolasi pesan JSON.

Penanganan teks

Teks di kedua sisi token interpolasi dipangkas spasi kosongnya. Teks yang menggunakan karakter % (misalnya, saat merujuk ke persentase) harus menggunakan %% agar tidak ditafsirkan sebagai token interpolasi.

Blockly juga otomatis mengganti karakter baris baru (\n) dalam string pesan dengan input akhir baris.

JSON

{
  "message0": "set %1\nto %2",
  "args0": [
    {"type": "field_variable", ...}, // token %1
    {"type": "input_value", ...},    // token %2
  ]
}

Petakan karakter baris baru dalam "set %1\nto %2" ke input akhir baris.

Array argumen

Setiap string pesan dipasangkan dengan array args dengan jumlah yang sama. Misalnya, message0 cocok dengan args0. Token interpolasi (%1, %2, ...) merujuk ke item array args dan harus cocok dengan array args0 sepenuhnya: tidak ada duplikat, tidak ada penghilangan. Nomor token merujuk pada urutan item dalam array argumen; nomor tersebut tidak harus muncul secara berurutan dalam string pesan.

Setiap objek dalam array argumen memiliki string type. Parameter lainnya bervariasi, bergantung pada jenisnya:

Anda juga dapat menentukan kolom kustom dan input kustom sendiri serta meneruskannya sebagai argumen.

Kolom alternatif

Setiap objek juga dapat memiliki kolom alt. Jika Blockly tidak mengenali type objek, maka objek alt akan digunakan sebagai gantinya. Misalnya, jika kolom baru bernama field_time ditambahkan ke Blockly, blok yang menggunakan kolom ini dapat menggunakan alt untuk menentukan penggantian field_input untuk Blockly versi lama:

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"
        }
    }
  ]
}

Objek alt dapat memiliki objek alt-nya sendiri, sehingga memungkinkan penggabungan. Pada akhirnya, jika Blockly tidak dapat membuat objek dalam array args0 (setelah mencoba objek alt apa pun), objek tersebut akan dilewati.