このドキュメントでは、JSON を使用して、ブロックの入力、フィールド（ラベルを含む）、接続を定義する方法について説明します。これらの用語に慣れていない場合は、先に進む前にブロックの構造をご覧ください。
JavaScript で 入力、フィールド、接続を定義することもできます。
概要
JSON では、1 つ以上のメッセージ文字列（message0、message1、...）と対応する引数配列（args0、args1、...）を使用して、ブロックの構造を記述します。メッセージ文字列は、ラベルに変換されるテキストと、接続とラベル以外のフィールドの位置を示す補間トークン（%1、%2、...）で構成されます。引数配列は、補間トークンを処理する方法を記述します。
たとえば、次のブロックがあるとします。
これは、次の 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 つのフィールドを持つ単一の値入力が作成されます。
例 2
JSON
{
"message0": "%1 + %2",
"args0": [
{"type": "input_value", ...} // token %1
{"type": "input_value", ...} // token %2
],
}
これにより、2 つの値入力が作成されます。1 つ目はフィールドがなく、2 つ目は 1 つの
フィールド（"+"）があります。
例 3
JSON
{
"message0": "%1 + %2 %3",
"args0": [
{"type": "input_value", ...} // token %1
{"type": "input_end_row", ...} // token %2
{"type": "input_value", ...} // token %3
],
}
これにより、次のものが作成されます。
- フィールドのない値入力
- ラベル フィールド（
"+"）を含む行末入力 。これにより、次の値入力が 新しい行にレンダリングされます。 - フィールドのない値入力。
メッセージの末尾にあるダミー入力
message 文字列がテキストまたはフィールドで終わる場合、それらを含むダミー入力の補間トークンを追加する必要はありません。Blockly が自動的に追加します。たとえば、次のように lists_isEmpty ブロックを定義する代わりに、
JSON
{
"message0": "%1 is empty %2",
"args0": [
{"type": "input_value", ...} // token %1
{"type": "input_dummy", ...} // token %2
],
}
Blockly にダミー入力を追加して、次のように定義できます。
JSON
{
"message0": "%1 is empty",
"args0": [
{"type": "input_value", ...} // token %1
],
}
末尾のダミー入力が自動的に追加されるため、翻訳者は補間トークンを記述する引数を変更せずに message を変更できます。詳細については、補間トークン
順序をご覧ください。
implicitAlign
まれに、自動的に作成された末尾のダミー入力を揃える必要があります
"RIGHT"または"CENTRE"に。指定しない場合のデフォルトは "LEFT" です。
次の例では、message0 は "send email to %1 subject %2 secure %3"
で、Blockly は 3 行目のダミー入力を自動的に追加します。
implicitAlign0 を "RIGHT" に設定すると、この行が右揃えになります。
implicitAlign
は、JSON
ブロック定義で明示的に定義されていないすべての入力に適用されます。これには、改行文字
('\n')を置き換える行末入力も含まれます。また、implicitAlign0と同じ動作をする非推奨のプロパティ
lastDummyAlign0もあります。
RTL（アラビア語とヘブライ語）のブロックを設計する場合、左と右が逆になります。
したがって、"RIGHT" はフィールドを左に揃えます。
複数のメッセージ
一部のブロックは、自然に 2 つ以上の別々の部分に分割されます。 2 行の繰り返しブロックについて考えてみましょう。
このブロックが 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
],
}
JSON 形式では、message、args、implicitAlign のプロパティをいくつでも定義できます。0 から始まり、順番に増えていきます。Block Factory ではメッセージを複数の部分に分割できませんが、手動で行うのは簡単です。
補間トークンの順序
ブロックをローカライズするときに、メッセージ内の補間トークンの順序を変更する必要がある場合があります。これは、英語とは語順が異なる言語では特に重要です。たとえば、メッセージ "set %1 to %2" で定義されたブロック
から始めます。
ここで、"set %1 to %2" を逆にして
"put %2 in %1" にする必要がある架空の言語について考えてみましょう。メッセージ（補間トークンの順序を含む）を変更し、引数配列を変更しないと、次のブロックになります。
Blockly は、フィールドの順序を自動的に変更し、ダミー 入力を作成して、外部入力から内部入力に切り替えました。
メッセージ内の補間トークンの順序を変更できるため、ローカライズが容易になります。詳細については、JSON メッセージ の補間をご覧ください。
テキストの処理
補間トークンの両側のテキストは空白文字でトリミングされます。
文字 % を使用するテキスト（パーセンテージを参照する場合など）は、補間トークンとして解釈されないように
%% を使用する必要があります。
また、Blockly はメッセージ文字列内の改行文字（\n）を行末入力に自動的に置き換えます。
JSON
{
"message0": "set %1\nto %2",
"args0": [
{"type": "field_variable", ...}, // token %1
{"type": "input_value", ...}, // token %2
]
}
引数配列
各メッセージ文字列は、同じ数の args 配列とペアになります。 たとえば、message0 は args0 とペアになります。 補間トークン
(%1、%2、...)は args 配列の項目を参照し、
args0 配列と完全に一致する必要があります。重複や欠落はありません。トークン番号は引数配列内の項目の順序を表します。メッセージ文字列内で順番に発生する必要はありません。
引数配列内のすべてのオブジェクトには type 文字列があります。残りのパラメータはタイプによって異なります。
独自のカスタム フィールドと カスタム入力を定義して、引数として渡すこともできます。
alt フィールド
すべてのオブジェクトに 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 オブジェクトを試行した後）、そのオブジェクトはスキップされます。