Vérification de la connexion

Les vérifications de connexion limitent les connexions (et donc les blocs) pouvant se connecter les unes aux autres.

Les vérifications de connexion sont utiles pour les types de modélisation. Par exemple, les trois blocs suivants n'ont aucune raison d'être connectés, car ils représentent du code qui renvoie différents types:

Vous pouvez utiliser des vérifications de connexion pour empêcher ces blocs de se connecter. Cela fournit aux utilisateurs des commentaires instantanés et évite de nombreuses erreurs simples.

Fonctionnement

Chaque connexion peut être associée à une "vérification de connexion", qui est un tableau de chaînes nullable.

Deux connexions peuvent se connecter si:

1. Il s'agit de types compatibles (par exemple, une sortie connectée à une entrée).
2. Ils ont au moins une chaîne en commun dans leur vérification de connexion.

Par exemple, les connexions avec les deux vérifications suivantes peuvent se connecter, car elles partagent la chaîne 'apple':

['apple', 'ball', 'cat']
['apple', 'bear', 'caterpillar']

Toutefois, les connexions avec ces deux vérifications n'ont pas pu être établies, car elles ne partagent aucune chaîne:

['apple', 'ball', 'cat']
['ape', 'bear', 'caterpillar']

Il existe un autre cas particulier. Si l'un des tableaux est null, les deux connexions peuvent également se connecter. Vous pouvez ainsi définir des connexions pouvant se connecter à n'importe quoi.

null
['ape', 'bear', 'caterpillar]

Important :Les chaînes utilisées dans les vérifications de connexion n'ont aucune signification intrinsèque. Par exemple, l'utilisation de la chaîne 'Number' ne garantit pas qu'une connexion représente un nombre. Ils ne sont utilisés que pour faire correspondre d'autres chaînes.

Important :Les types de blocs, tels que 'math_number', et les vérifications de connexion sont des ensembles de chaînes entièrement distincts. L'inclusion d'un type de bloc dans une vérification de connexion n'entraîne pas la connexion des blocs de ce type.

Exemples

Pour obtenir une liste d'exemples d'utilisation des vérifications de connexion, consultez le guide de bonnes pratiques sur les vérifications de connexion.

Définir des vérifications

Par défaut, toutes les connexions sont soumises à une vérification de connexion null, ce qui signifie qu'elles peuvent se connecter à n'importe quoi. Les vérifications de connexion doivent être attribuées manuellement.

La manière dont vous attribuez des vérifications de connexion aux connexions diffère selon que vous utilisez des définitions de blocs JSON ou des définitions de blocs JavaScript.

JSON

Pour les connexions de niveau supérieur, vous attribuez la vérification directement à la propriété qui définit la connexion. La valeur que vous attribuez peut être null, une chaîne (qui devient la seule entrée de la vérification de la connexion) ou un tableau de chaînes.

{
  'type': 'custom_value_block',

  'output': 'a connection check entry',
},
{
  'type': 'custom_statement_block',

  'nextStatement': null, // null check
  'previousStatement': ['four', 'connection', 'check', 'entries']
}

Pour les entrées, vous pouvez attribuer la vérification à une propriété check de la définition de l'entrée. Si la propriété check n'existe pas, la vérification est considérée comme null. La valeur que vous attribuez peut être une chaîne ou un tableau de chaînes.

{
  'type': 'custom_block',
  'message0': '%1 %2',

  'args0': [
    {
      'type': 'input_value',
      'check': 'a connection check entry' // Accepts custom_value_block
    },
    {
      'type': 'input_statement',
      'check': ['two', 'entries'] // Accepts custom_statement_block
    }
  ]
}

JavaScript

Pour les connexions de niveau supérieur, vous pouvez transmettre la vérification directement à la méthode qui définit la connexion. Si vous ne transmettez pas de valeur, la vérification est considérée comme null. La valeur que vous transmettez peut être une chaîne (qui devient la seule entrée de la vérification de la connexion) ou un tableau de chaînes.

Blockly.Blocks['custom_value_block'] = {
  init: function() {
    this.setOutput(true, 'a connection check entry');
  }
};
Blockly.Blocks['custom_statement_block'] = {
  init: function() {
    this.setNextStatement(true); // null check
    this.setPreviousStatement(true, ['four', 'connection', 'check', 'entries']);
  }
};

Pour les entrées, vous pouvez transmettre la vérification à la méthode setCheck après avoir défini l'entrée. Si la méthode setCheck n'est pas appelée, la vérification est considérée comme null. La valeur que vous transmettez peut être une chaîne ou un tableau de chaînes.

Blockly.Blocks['custom_block'] = {
  init: function() {
    this.appendValueInput('NAME')
        .setCheck('a connection check entry'); // Accepts custom_value_block
    this.appendStatementInput('NAME')
        .setCheck(['two', 'entries']); // Accepts custom_statement_block
  }
};

Chaînes de vérification intégrées

Les blocs intégrés comportent des vérifications de connexion avec les valeurs 'Array', 'Boolean', 'Colour', 'Number' et 'String'. Si vous souhaitez que vos blocs interagissent avec les blocs intégrés, vous pouvez utiliser ces valeurs pour les rendre compatibles.

Limites

Ce système est assez robuste et peut résoudre de nombreux cas d'utilisation, mais il présente quelques limites.

Limiter le contexte plus large

Ce système ne permet pas, à lui seul, de limiter le "contexte plus large" dans lequel une connexion est autorisée à se connecter. Par exemple, vous ne pouvez pas dire qu'un bloc break ne peut exister que dans un bloc loop. Le système de vérification de la connexion ne tient compte que des deux connexions immédiates.

Pour ce faire, vous pouvez utiliser le système d'événements pour écouter les événements de déplacement de bloc et vérifier si le bloc est mal positionné.

Blockly.Blocks['custom_block'] = {
  init: function() { }

  onchange: function(e) {
    if (this.workspace.isDragging()) return;
    if (e.type !== Blockly.Events.BlockMove) return;
    if (!this.getSurroundLoop()) this.outputConnection.disconnect();
  }

  loopTypes: new Set(); // Your valid *block types* (not connection checks).

  getSurroundLoop: function () {
    let block = this.getSurroundParent();
    do {
      if (loopTypes.has(block.type)) return block;
      block = block.getSurroundParent();
    } while (block);
    return null;
  },
}

Types génériques

Ce système ne permet pas, à lui seul, de définir des types génériques. Par exemple, vous ne pouvez pas créer de bloc "Identité" qui "renvoie" quelle que soit son entrée.

Vous pouvez dans une certaine mesure y parvenir en modifiant activement la vérification de la connexion à la sortie du bloc pour qu'elle corresponde à son entrée. Vous pouvez le faire à l'aide du système d'événements pour écouter les événements de déplacement de bloc.

Blockly.Blocks['custom_block'] = {
  init: function() { }

  onchange: function(e) {
    if (e.type !== Blockly.Events.BlockMove) return;
    this.setOutput(
        true, this.getInputTargetBlock()?.outputConnection.getCheck());
  }
}

Toutefois, si le bloc connecté est également générique, cela ne fonctionne pas correctement. Il n'existe aucune solution de contournement pour ce cas.

Outils de vérification de la connexion

Si ce système ne convient pas à votre cas d'utilisation, vous pouvez également modifier la façon dont les vérifications de connexion sont comparées en créant un outil de vérification de la connexion personnalisé.

Par exemple, si vous souhaitez créer un système plus avancé qui gère certaines des limites de celui-ci, vous pouvez créer un vérificateur de connexion personnalisé.