Estructura de bloques en JSON

En este documento, analizaremos cómo usar JSON para definir las entradas, los campos (incluidas las etiquetas) y las conexiones en tu bloque. Si no estás familiarizado con estos términos, consulta Anatomía de un bloque antes de continuar.

También puedes definir tus entradas, campos y conexiones en JavaScript.

Descripción general

En JSON, describes la estructura de un bloque con una o más cadenas de mensajes (message0, message1, ...) y sus arrays de argumentos correspondientes (args0, args1, ...). Las cadenas de mensajes constan de texto, que se convierte en etiquetas, y tokens de interpolación (%1, %2, ...), que marcan las ubicaciones de las conexiones y los campos que no son de etiqueta. Los arrays de argumentos describen cómo controlar los tokens de interpolación.

Por ejemplo, este bloque:

Es un bloque de configuración de variables. Tiene la etiqueta "establecer", un menú desplegable para elegir la variable, la etiqueta "en" y una entrada de valor.

se define con el siguiente JSON:

JSON

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

El primer token de interpolación (%1) representa un campo variable (type: "field_variable"). Se describe con el primer objeto del args0 array. El segundo token (%2) representa la conexión de entrada al final de una entrada de valor (type: "input_value"). Se describe con el segundo objeto del args0 array.

Mensajes y entradas

Cuando un token de interpolación marca una conexión, en realidad marca el final de la entrada que contiene la conexión. Esto se debe a que las conexiones en las entradas de valor y de instrucción se renderizan al final de la entrada. La entrada contiene todos los campos (incluidas las etiquetas) después de la entrada anterior y hasta el token actual. En las siguientes secciones, se muestran mensajes de muestra y las entradas que se crean a partir de ellos.

Ejemplo 1

JSON

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

Esto crea una sola entrada de valor con tres campos: una etiqueta ("set"), un campo de variable y otra etiqueta ("to").

Asigna el mensaje "set %1 to %2" a una entrada de valor con tres campos.

Ejemplo 2

JSON

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

Esto crea dos entradas de valor. La primera no tiene campos y la segunda tiene un campo ("+").

Asigna el mensaje "%1 + %2" a dos entradas de valor.

Ejemplo 3

JSON

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

Esto crea lo siguiente:

  • Una entrada de valor sin campos
  • Una entrada de fin de fila con un campo de etiqueta ("+"), que hace que la siguiente entrada de valor se renderice en una fila nueva
  • Una entrada de valor sin campos

Asigna el mensaje "%1 + %2 %3" a dos entradas de valor y una entrada de fin de fila.

Entrada ficticia al final del mensaje

Si tu cadena message termina con texto o campos, no necesitas agregar un token de interpolación para la entrada ficticia que los contiene. Blockly lo agrega por ti. Por ejemplo, en lugar de definir un bloque lists_isEmpty de esta manera:

JSON

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

Asigna el mensaje "%1 está vacío" a una entrada de valor y a una entrada simulada creada automáticamente.

puedes dejar que Blockly agregue la entrada ficticia y la defina de esta manera:

JSON

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

Asigna el mensaje "%1 está vacío" a una entrada de valor y a una entrada simulada creada automáticamente.

La adición automática de una entrada ficticia final permite que los traductores cambien message sin necesidad de modificar los argumentos que describen los tokens de interpolación. Para obtener más información, consulta Orden de los tokens de interpolación.

implicitAlign

En casos excepcionales, la entrada ficticia final creada automáticamente debe alinearse a "RIGHT" o "CENTRE". El valor predeterminado, si no se especifica, es "LEFT".

En el siguiente ejemplo, message0 es "send email to %1 subject %2 secure %3" y Blockly agrega automáticamente una entrada ficticia para la tercera fila. Si se configura implicitAlign0 como "RIGHT", se fuerza a que esta fila se alinee a la derecha.

Es un bloqueo para enviar correos electrónicos. La primera fila tiene la etiqueta "Enviar correo electrónico a" y una entrada de valor. La segunda fila tiene la etiqueta "subject" y una entrada de valor. La tercera línea tiene la etiqueta "seguro" y una casilla de verificación; está alineada a la derecha.

implicitAlign se aplica a todas las entradas que no se definen de forma explícita en la definición de bloque JSON, incluidas las entradas de fin de fila que reemplazan los caracteres de salto de línea ('\n'). También existe la propiedad obsoleta lastDummyAlign0 que tiene el mismo comportamiento que implicitAlign0.

Cuando se diseñan bloques para RTL (árabe y hebreo), la izquierda y la derecha se invierten. Por lo tanto, "RIGHT" alinearía los campos a la izquierda.

Varios mensajes

Algunos bloques se dividen naturalmente en dos o más partes separadas. Considera este bloque de repetición que tiene dos filas:

Un bloque de repetición con dos filas. La primera fila tiene la etiqueta "repeat", una entrada de valor y la etiqueta "times". La segunda fila tiene la etiqueta "do" y una entrada de instrucción.

Si este bloque se describiera con un solo mensaje, la message0 propiedad sería "repeat %1 times %2 do %3", en la que %2 representa una entrada de fin de fila. Esta cadena es incómoda para un traductor porque es difícil explicar lo que significa la sustitución %2. Es posible que la entrada de fin de fila %2 ni siquiera sea deseable en algunos idiomas. Además, puede haber varios bloques que deseen compartir el texto de la segunda fila. Un mejor enfoque es usar más de una propiedad message y 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
  ],
}

Asigna el mensaje "repite %1 veces" a una entrada de valor y a una entrada ficticia creada automáticamente, y el mensaje "haz %1" a una entrada de instrucción.

Se puede definir cualquier cantidad de propiedades message, args y implicitAlign en el formato JSON, comenzando con 0 y aumentando de forma secuencial. Ten en cuenta que Block Factory no puede dividir mensajes en varias partes, pero hacerlo de forma manual es sencillo.

Orden de los tokens de interpolación

Cuando localizas bloques, es posible que debas cambiar el orden de los tokens de interpolación en un mensaje. Esto es particularmente importante en idiomas que tienen un orden de palabras diferente al inglés. Por ejemplo, comenzamos con un bloque definido por el mensaje "set %1 to %2":

Un bloque de configuración de variables con la etiqueta "set", un campo de menú desplegable para la variable, la etiqueta "to" y una entrada de valor externo.

Ahora considera un idioma hipotético en el que "set %1 to %2" debe invertirse para decir "put %2 in %1". Si cambias el mensaje (incluido el orden de los tokens de interpolación) y dejas el array de argumentos sin cambios, se obtiene el siguiente bloque:

Un bloque de configuración de variables con la etiqueta "put", una entrada de valor intercalado, la etiqueta "to" y un campo desplegable para la variable.

Blockly cambió automáticamente el orden de los campos, creó una entrada ficticia input, y cambió de entradas externas a internas inputs.

La capacidad de cambiar el orden de los tokens de interpolación en un mensaje facilita la localización. Para obtener más información, consulta Interpolación de mensajes JSON.

Control de texto

El texto a cada lado de un token de interpolación se recorta con espacios en blanco. El texto que usa el carácter % (p.ej., cuando se hace referencia a un porcentaje) debe usar %% para que no se interprete como un token de interpolación.

Blockly también reemplaza automáticamente cualquier carácter de salto de línea (\n) en la cadena de mensajes por una entrada de fin de fila.

JSON

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

Asigna el carácter de salto de línea en "set %1\nto %2" a una entrada de fin de fila.

Arrays de argumentos

Cada cadena de mensajes se combina con un array args del mismo número. Por ejemplo, message0 va con args0. Los tokens de interpolación (%1, %2, ...) hacen referencia a los elementos del array args y deben coincidir por completo con el array args0: sin duplicados ni omisiones. Los números de token hacen referencia al orden de los elementos en el array de argumentos; no es necesario que aparezcan en orden en una cadena de mensajes.

Cada objeto del array de argumentos tiene una cadena type. El resto de los parámetros varían según el tipo:

También puedes definir tus propios campos personalizados y entradas personalizadas y pasarlos como argumentos.

Campos alternativos

Cada objeto también puede tener un campo alt. En el caso de que Blockly no reconozca el type del objeto, se usa el objeto alt en su lugar. Por ejemplo, si se agrega un campo nuevo llamado field_time a Blockly, los bloques que usan este campo podrían usar alt para definir una alternativa field_input para versiones anteriores de 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"
        }
    }
  ]
}

Un objeto alt puede tener su propio objeto alt, lo que permite el encadenamiento. En última instancia, si Blockly no puede crear un objeto en el array args0 (después de intentar cualquier objeto alt), ese objeto se omite.