Блочная структура в JSON

В этом документе мы обсудим, как использовать JSON для определения входных данных, полей (включая метки) и соединений в вашем блоке. Если вы не знакомы с этими терминами, прежде чем продолжить, прочтите раздел «Анатомия блока» .

Вы также можете определить свои входные данные, поля и соединения в JavaScript .

Обзор

В JSON вы описываете структуру блока с помощью одной или нескольких строк сообщений ( 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 ) представляет входное соединение в конце ввода значения ( type: "input_value" ). Его описывает второй объект массива args0 .

Сообщения и входные данные

Когда токен интерполяции отмечает соединение, он на самом деле отмечает конец ввода, содержащего соединение. Это связано с тем, что связи во входных значениях и операторах отображаются в конце ввода. Входные данные содержат все поля (включая метки) после предыдущего ввода и до текущего токена. В следующих разделах показаны примеры сообщений и входные данные, созданные на их основе.

Пример 1

JSON

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

Это создает одно входное значение с тремя полями: меткой ( "set" ), переменным полем и еще одной меткой ( "to" ).

Пример 2

JSON

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

Это создает два входных значения. В первом нет полей, а во втором есть одно поле ( "+" ).

Пример 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 без необходимости изменять аргументы, описывающие токены интерполяции. Дополнительные сведения см. в разделе Порядок токенов интерполяции .

неявноеВыравнивание

В редких случаях автоматически созданный конечный фиктивный ввод необходимо выровнять по "RIGHT" или "CENTRE" . По умолчанию, если не указано иное, используется "LEFT" .

В приведенном ниже примере message0 — это "send email to %1 subject %2 secure %3" , и Blockly автоматически добавляет фиктивный ввод для третьей строки. Установка для implicitAlign0 значения "RIGHT" приводит к выравниванию этой строки по правому краю.

implicitAlign применяется ко всем входным данным, которые не определены явно в определении блока JSON, включая входные данные конца строки, которые заменяют символы новой строки ( '\n' ) . Существует также устаревшее свойство lastDummyAlign0 , которое ведет себя так же, как и implicitAlign0 .

При проектировании блоков для RTL (арабского и иврита) левое и правое меняются местами. Таким образом, "RIGHT" будет выравнивать поля по левому краю.

Несколько сообщений

Некоторые блоки естественным образом делятся на две или более отдельных частей. Рассмотрим этот повторяющийся блок, который имеет две строки:

Если бы этот блок был описан одним сообщением, свойство message0 было бы "repeat %1 times %2 do %3" , где %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 и последовательно увеличиваясь. Обратите внимание, что Фабрика блоков не способна разбивать сообщения на несколько частей, но сделать это вручную несложно.

Порядок токенов интерполяции

При локализации блоков вам может потребоваться изменить порядок токенов интерполяции в сообщении. Это особенно важно для языков, порядок слов в которых отличается от английского. Например, мы начали с блока, определенного сообщением "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 . Остальные параметры варьируются в зависимости от типа:

• Поля :
  • field_input
  • field_dropdown
  • field_checkbox
  • field_colour
  • field_number
  • field_angle
  • field_variable
  • field_label
  • field_image .
• Входы :
  • input_value
  • input_statement
  • input_dummy
  • input_end_row

Вы также можете определить свои собственные настраиваемые поля и настраиваемые входные данные и передать их в качестве аргументов.

альтернативные поля

Каждый объект также может иметь поле alt . В случае, если Blockly не распознает type объекта, вместо него используется alt объект. Например, если в Blockly добавлено новое поле с именем field_time , блоки, использующие это поле, могут использовать alt для определения резервного варианта field_input для старых версий 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"
        }
    }
  ]
}

alt объект может иметь свой собственный alt объект, что позволяет создавать цепочки. В конечном счете, если Blockly не может создать объект в массиве args0 (после попытки использования любых alt объектов), этот объект просто пропускается.