Blockly は 2025 年 11 月 10 日に Raspberry Pi Foundation に移行します。ブログとよくある質問をご覧ください。

このページは Cloud Translation API によって翻訳されました。

JSON のブロック構造

このドキュメントでは、JSON を使用してブロックの入力、フィールド（ラベルを含む）、接続を定義する方法について説明します。これらの用語に慣れていない場合は、続行する前にブロックの構造をご覧ください。

入力、フィールド、接続を JavaScript で定義することもできます。

概要

JSON では、1 つ以上のメッセージ文字列（message0、message1、...）とそれに対応する引数配列（args0、args1、...）を使用して、ブロックの構造を記述します。メッセージ文字列は、ラベルに変換されるテキストと、接続と非ラベルフィールドの位置を示す補間トークン（%1、%2、...）で構成されます。引数配列は、補間トークンの処理方法を記述します。

たとえば、次のブロックについて考えてみましょう。

変数セッターブロック。「set」というラベル、変数を選択するためのプルダウン、ラベル「to」、値の入力欄があります。

は次の JSON で定義されます。

JSON

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

最初の補間トークン（%1）は、変数フィールド（type: "field_variable"）を表します。これは、args0 配列の最初のオブジェクトで記述されます。2 番目のトークン（%2）は、値入力（type: "input_value"）の末尾にある入力接続を表します。これは、args0 配列の 2 番目のオブジェクトで記述されます。

メッセージと入力

補間トークンが接続をマークする場合、実際には接続を含む入力の終わりをマークしています。これは、値とステートメントの入力の接続が入力の最後にレンダリングされるためです。入力には、前の入力以降のすべてのフィールド（ラベルを含む）と現在のトークンが含まれます。次のセクションでは、サンプルメッセージと、それらから作成される入力について説明します。

例 1

JSON

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

これにより、ラベル（"set"）、変数フィールド、別のラベル（"to"）の 3 つのフィールドを含む単一値入力が作成されます。

メッセージ「%1 を %2 に設定」を 3 つのフィールドを含む値入力にマッピングします。

例 2

JSON

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

これにより、2 つの値入力が作成されます。1 つ目はフィールドがなく、2 つ目は 1 つのフィールド（"+"）があります。

メッセージ「%1 + %2」を 2 つの値入力にマッピングします。

例 3

JSON

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

これにより、次のものが作成されます。

フィールドのない値の入力、
ラベルフィールド（"+"）を含む行末入力。これにより、次の値入力が新しい行にレンダリングされます。
フィールドのない値入力。

メッセージ「%1 + %2 %3」を 2 つの値入力と行末入力にマッピングします。

メッセージの末尾にあるダミー入力

message 文字列がテキストまたはフィールドで終わる場合、それらを含むダミー入力の補間トークンを追加する必要はありません。Blockly が自動的に追加します。たとえば、次のように lists_isEmpty ブロックを定義するのではなく、

JSON

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

メッセージ「%1 は空です」を値入力と自動的に作成されたダミー入力にマッピングします。

Blockly にダミー入力を追加して、次のように定義できます。

JSON

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

メッセージ「%1 は空です」を値入力と自動的に作成されたダミー入力にマッピングします。

末尾のダミー入力が自動的に追加されるため、変換ツールは補間トークンを記述する引数を変更することなく message を変更できます。詳細については、補間トークンの順序をご覧ください。

implicitAlign

まれに、自動的に作成された末尾のダミー入力を "RIGHT" または "CENTRE" に合わせる必要があります。指定しない場合のデフォルトは "LEFT" です。

次の例では、message0 は "send email to %1 subject %2 secure %3" であり、Blockly は 3 行目のダミー入力を自動的に追加します。implicitAlign0 を "RIGHT" に設定すると、この行は強制的に右揃えになります。

メール送信用のブロック。最初の行には「send email to」というラベルと値の入力欄があります。2 行目には、「件名」というラベルと値の入力欄があります。3 行目には「secure」というラベルとチェックボックスがあり、右揃えになっています。

implicitAlign は、JSON ブロック定義で明示的に定義されていないすべての入力に適用されます。これには、改行文字（'\n'）を置き換える行末入力も含まれます。implicitAlign0 と同じ動作をする非推奨のプロパティ lastDummyAlign0 もあります。

RTL（アラビア語とヘブライ語）用のブロックを設計する場合、左と右が逆になります。したがって、"RIGHT" はフィールドを左揃えにします。

複数のメッセージ

一部のブロックは、自然に 2 つ以上の別々の部分に分割されます。2 つの行を含む次の繰り返しブロックを考えてみましょう。

2 行の繰り返しブロック。最初の行には、「repeat」というラベル、値の入力欄、「times」というラベルがあります。2 行目には「do」というラベルとステートメント入力があります。

このブロックを 1 つのメッセージで記述する場合、message0 プロパティは "repeat %1 times %2 do %3" になります。ここで、%2 は行末の入力を表します。この文字列は、%2 の置換が何を意味するのかを説明するのが難しいため、翻訳者にとって不自然です。また、一部の言語では %2 行末入力が望ましくない場合もあります。2 行目のテキストを共有したいブロックが複数ある場合もあります。より適切な方法は、複数の message プロパティと 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
  ],
}

メッセージ「%1 回繰り返す」を値入力と自動的に作成されたダミー入力にマッピングし、メッセージ「%1 を実行する」をステートメント入力にマッピングします。

JSON 形式では、message、args、implicitAlign プロパティを任意の数だけ定義できます。0 から始まり、順に増分します。ブロックファクトリではメッセージを複数の部分に分割できませんが、手動で分割するのは簡単です。

補間トークンの順序

ブロックをローカライズする際に、メッセージ内の補間トークンの順序を変更する必要がある場合があります。これは、英語とは語順が異なる言語で特に重要です。たとえば、メッセージ "set %1 to %2" で定義されたブロックから始めます。

「set」というラベルの付いた変数設定ブロック、変数のプルダウンフィールド、「to」というラベル、外部値入力。

ここで、"set %1 to %2" を反転させて "put %2 in %1" とする必要がある架空の言語を考えてみましょう。メッセージ（補間トークンの順序を含む）を変更し、引数配列を変更しないと、次のブロックが生成されます。

ラベル「put」、インライン値入力、ラベル「to」、変数のプルダウンフィールドを含む変数セッターブロック。

Blockly はフィールドの順序を自動的に変更し、ダミー入力を作成して、外部入力から内部入力に切り替えました。

メッセージ内の補間トークンの順序を変更できるため、ローカライズが容易になります。詳細については、JSON メッセージの補間をご覧ください。

テキストの処理

補間トークンの両側のテキストは空白文字が削除されます。文字 % を使用するテキスト（パーセンテージを参照する場合など）では、補間トークンとして解釈されないように %% を使用する必要があります。

Blockly は、メッセージ文字列内の改行文字（\n）を自動的に行末入力に置き換えます。

JSON

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

$「set %1\nto %2」の改行文字を行末入力にマッピングします。$

引数配列

各メッセージ文字列は、同じ数の args 配列とペアになっています。たとえば、message0 は args0 と組み合わされます。補間トークン（%1、%2 など）は args 配列の項目を参照し、args0 配列と完全に一致する必要があります。重複や省略はできません。トークン番号は引数配列内のアイテムの順序を指します。メッセージ文字列内で順序どおりに発生する必要はありません。

引数配列内のすべてのオブジェクトには type 文字列があります。残りのパラメータはタイプによって異なります。

フィールド:
入力:
- input_value
- input_statement
- input_dummy
- input_end_row

独自のカスタムフィールドとカスタム入力を定義して、引数として渡すこともできます。

代替フィールド

すべてのオブジェクトに alt フィールドを含めることもできます。Blockly がオブジェクトの type を認識しない場合は、代わりに alt オブジェクトが使用されます。たとえば、field_time という名前の新しいフィールドが Blockly に追加された場合、このフィールドを使用するブロックは alt を使用して、古いバージョンの Blockly の field_input フォールバックを定義できます。

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

alt オブジェクトには独自の alt オブジェクトを含めることができるため、チェーン化が可能です。最終的に、Blockly が args0 配列内にオブジェクトを作成できない場合（alt オブジェクトを試行した後）、そのオブジェクトはスキップされます。

JSON のブロック構造 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

JSON

メッセージと入力

例 1

JSON

例 2

JSON

例 3

JSON

メッセージの末尾にあるダミー入力

JSON

JSON

implicitAlign

複数のメッセージ

JSON

補間トークンの順序

テキストの処理

JSON

引数配列

代替フィールド

JSON

JSON のブロック構造