Structure de bloc en JSON

Dans ce document, nous allons voir comment utiliser JSON pour définir les entrées, les champs (y compris les libellés) et les connexions de votre bloc. Si ces termes ne vous sont pas familiers, consultez Anatomie d'un bloc avant de continuer.

Vous pouvez également définir vos entrées, vos champs et vos connexions en JavaScript.

Présentation

En JSON, vous décrivez la structure d'un bloc avec une ou plusieurs chaînes de message (message0, message1, ...) et leurs tableaux d'arguments correspondants (args0, args1, ...). Les chaînes de message se composent de texte, qui est converti en libellés, et de jetons d'interpolation (%1, %2, ...), qui marquent l'emplacement des connexions et des champs non libellés. Les tableaux d'arguments décrivent comment gérer les jetons d'interpolation.

Par exemple, ce bloc :

Bloc de définition de variable. Il comporte le libellé "définir", un menu déroulant permettant de choisir la variable, le libellé "sur" et un champ de saisie de la valeur.

est défini par le JSON suivant :

JSON

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

Le premier jeton d'interpolation (%1) représente un champ de variable (type: "field_variable"). Il est décrit par le premier objet du tableau args0. Le deuxième jeton (%2) représente la connexion d'entrée à la fin d'une entrée de valeur (type: "input_value"). Il est décrit par le deuxième objet du tableau args0.

Messages et saisies

Lorsqu'un jeton d'interpolation marque une connexion, il marque en réalité la fin de l'entrée qui contient la connexion. En effet, les connexions dans les entrées de valeur et d'instruction sont affichées à la fin de l'entrée. L'entrée contient tous les champs (y compris les libellés) après l'entrée précédente et jusqu'au jeton actuel. Les sections suivantes présentent des exemples de messages et les entrées qui sont créées à partir de ceux-ci.

Exemple 1

JSON

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

Cela crée une entrée à valeur unique avec trois champs : un libellé ("set"), un champ de variable et un autre libellé ("to").

Mappez le message "set %1 to %2" à une entrée de valeur avec trois champs.

Exemple 2

JSON

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

Cela crée deux entrées de valeur. Le premier ne comporte aucun champ, tandis que le second en comporte un ("+").

Mappez le message "%1 + %2" à deux entrées de valeur.

Exemple 3

JSON

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

Cela crée :

  • Une valeur saisie sans champ
  • Une entrée de fin de ligne avec un champ de libellé ("+"), qui entraîne l'affichage de l'entrée de valeur suivante sur une nouvelle ligne.
  • Valeur saisie sans champ.

Mappez le message "%1 + %2 %3" à deux entrées de valeur et à une entrée de fin de ligne.

Entrée fictive à la fin du message

Si votre chaîne message se termine par du texte ou des champs, vous n'avez pas besoin d'ajouter de jeton d'interpolation pour l'entrée factice qui les contient. Blockly l'ajoute pour vous. Par exemple, au lieu de définir un bloc lists_isEmpty comme ceci :

JSON

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

Mappez le message "%1 est vide" à une entrée de valeur et à une entrée factice créée automatiquement.

Vous pouvez laisser Blockly ajouter l'entrée factice et la définir comme suit :

JSON

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

Mappez le message "%1 est vide" à une entrée de valeur et à une entrée factice créée automatiquement.

L'ajout automatique d'une entrée factice de fin permet aux traducteurs de modifier message sans avoir à modifier les arguments qui décrivent les jetons d'interpolation. Pour en savoir plus, consultez Ordre des jetons d'interpolation.

implicitAlign

Dans de rares cas, l'entrée factice de fin créée automatiquement doit être alignée sur "RIGHT" ou "CENTRE". Si aucune valeur n'est spécifiée, la valeur par défaut est "LEFT".

Dans l'exemple ci-dessous, message0 correspond à "send email to %1 subject %2 secure %3", et Blockly ajoute automatiquement une entrée factice pour la troisième ligne. Définir implicitAlign0 sur "RIGHT" force l'alignement de cette ligne à droite.

Bloc permettant d'envoyer un e-mail. La première ligne comporte le libellé "envoyer un e-mail à" et un champ de saisie de la valeur. La deuxième ligne comporte le libellé "subject" (sujet) et un champ de saisie de la valeur. La troisième ligne comporte le libellé "secure" (sécurisé) et une case à cocher. Elle est alignée à droite.

implicitAlign s'applique à toutes les entrées qui ne sont pas explicitement définies dans la définition du bloc JSON, y compris les entrées de fin de ligne qui remplacent les caractères de nouvelle ligne ('\n'). Il existe également la propriété obsolète lastDummyAlign0 qui a le même comportement que implicitAlign0.

Lorsque vous concevez des blocs pour les langues RTL (arabe et hébreu), la gauche et la droite sont inversées. Ainsi, "RIGHT" alignerait les champs à gauche.

Plusieurs messages

Certains blocs sont naturellement divisés en deux parties ou plus. Prenons l'exemple de ce bloc de répétition comportant deux lignes :

Bloc de répétition avec deux lignes. La première ligne comporte le libellé "repeat" (répéter), un champ de saisie de la valeur et le libellé "times" (fois). La deuxième ligne comporte le libellé "do" (faire) et une entrée d'instruction.

Si ce bloc était décrit par un seul message, la propriété message0 serait "repeat %1 times %2 do %3", où %2 représente une entrée de fin de ligne. Cette chaîne est difficile à traduire, car il est difficile d'expliquer ce que signifie la substitution %2. L'entrée de fin de ligne %2 peut également ne pas être souhaitée dans certaines langues. Il peut y avoir plusieurs blocs qui souhaitent partager le texte de la deuxième ligne. Une meilleure approche consiste à utiliser plusieurs propriétés message et 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
  ],
}

Mappez le message "repeat %1 times" (répéter %1 fois) à une entrée de valeur et à une entrée factice créée automatiquement, et le message "do %1" (faire %1) à une entrée d'instruction.

Vous pouvez définir un nombre quelconque de propriétés message, args et implicitAlign au format JSON, en commençant par 0 et en incrémentant de manière séquentielle. Notez que la fabrique de blocs n'est pas en mesure de diviser les messages en plusieurs parties, mais vous pouvez le faire facilement manuellement.

Ordre des jetons d'interpolation

Lorsque vous localisez des blocs, vous devrez peut-être modifier l'ordre des jetons d'interpolation dans un message. Cela est particulièrement important dans les langues dont l'ordre des mots est différent de celui de l'anglais. Par exemple, nous avons commencé par un bloc défini par le message "set %1 to %2" :

Bloc de définition de variable avec le libellé "set" (définir), un champ de menu déroulant pour la variable, le libellé "to" (à) et une entrée de valeur externe.

Prenons maintenant l'exemple d'une langue hypothétique dans laquelle "set %1 to %2" doit être inversé pour devenir "put %2 in %1". Si vous modifiez le message (y compris l'ordre des jetons d'interpolation) et que vous laissez le tableau d'arguments inchangé, vous obtenez le bloc suivant :

Bloc de définition de variable avec le libellé "put" (mettre), une entrée de valeur intégrée, le libellé "to" (à) et un champ de menu déroulant pour la variable.

Blockly a automatiquement modifié l'ordre des champs, créé une entrée factice et basculé des entrées externes aux entrées internes.

La possibilité de modifier l'ordre des jetons d'interpolation dans un message facilite la localisation. Pour en savoir plus, consultez Interpolation des messages JSON.

Gestion du texte

Le texte de part et d'autre d'un jeton d'interpolation est tronqué par les espaces. Le texte utilisant le caractère % (par exemple, lorsqu'il fait référence à un pourcentage) doit utiliser %% afin qu'il ne soit pas interprété comme un jeton d'interpolation.

Blockly remplace également automatiquement tout caractère de nouvelle ligne (\n) dans la chaîne de message par une entrée de fin de ligne.

JSON

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

Mappez le caractère de nouvelle ligne dans "set %1\nto %2" à une entrée de fin de ligne.

Tableaux d'arguments

Chaque chaîne de message est associée à un tableau args du même nombre. Par exemple, message0 va avec args0. Les jetons d'interpolation (%1, %2, etc.) font référence aux éléments du tableau args et doivent correspondre entièrement au tableau args0 : pas de doublons, pas d'omissions. Les numéros de jeton font référence à l'ordre des éléments dans le tableau d'arguments. Ils ne doivent pas nécessairement se trouver dans l'ordre dans une chaîne de message.

Chaque objet du tableau d'arguments comporte une chaîne type. Les autres paramètres varient en fonction du type :

Vous pouvez également définir vos propres champs personnalisés et entrées personnalisées, puis les transmettre en tant qu'arguments.

Champs "alt"

Chaque objet peut également comporter un champ alt. Si Blockly ne reconnaît pas le type de l'objet, l'objet alt est utilisé à la place. Par exemple, si un nouveau champ nommé field_time est ajouté à Blockly, les blocs utilisant ce champ peuvent utiliser alt pour définir une field_input de secours pour les anciennes versions 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 objet alt peut avoir son propre objet alt, ce qui permet l'enchaînement. En fin de compte, si Blockly ne parvient pas à créer un objet dans le tableau args0 (après avoir tenté de créer des objets alt), cet objet est simplement ignoré.