Publier des bibliothèques de blocs

Les plug-ins qui fournissent des bibliothèques de définitions de blocs sont un excellent moyen de partager vos blocs réutilisables avec la communauté Blockly. Pour que votre bibliothèque de blocs aussi polyvalents et utiles que possible, nous les avons élaborés.

Consignes

• Permettez aux utilisateurs d'installer facilement tous vos blocs, et de n'installer que certains blocs ou éléments de blocs de leur choix.
  • Facilitez l'installation de tout : pour ce faire, fournissez une fonction qui installe chaque élément requis par une seule définition de bloc (tels que les modificateurs, les extensions, les mixins, les champs, etc.). Vous pouvez également fournir une fonction qui installera tous les blocs proposés par votre plug-in en même temps.
  • Faites en sorte qu'il soit possible de choisir des pièces spécifiques: vous devez exporter tous les d'une définition de bloc séparément, de sorte qu'il est possible à l'utilisateur d'importer uniquement les pièces dont il a besoin pour créer les un bloc personnalisé similaire.
• Évitez d'utiliser des effets secondaires dans votre plug-in.
  • Les blocs, les champs, les extensions et les autres éléments ne doivent pas être installés en tant qu'effet secondaire du chargement de votre plug-in. Les utilisateurs doivent garder le contrôle sur quels éléments sont installés et quand. Cela permet aux utilisateurs d'importer les éléments dont ils ont besoin sans avoir à se soucier de l'installation d'éléments dont ils n'ont pas besoin.

• Utilisez le registre de champs JSON au lieu d'instancier directement de nouveaux champs.

  • Non recommandé : instancier directement un champ :

      const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(new Blockly.FieldNumber(123), 'NAME');
        }
      }
    

  • Recommandation : Registre de champs JSON :

      export const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(Blockly.fieldRegistry.fromJson({
                  name: 'field_number',
                  value: 123,
                }), 'NAME');
        }
      }
    

  • L'utilisation du registre de champs permet à un utilisateur de remplacer plus facilement l'implémentation du champ utilisé dans votre bloc sans avoir à modifier la définition du bloc.

• Ne faites pas d'hypothèses sur ce que l'utilisateur a déjà installé.

  • Si votre plug-in nécessite un champ personnalisé ou un autre plug-in, enregistrez ces champs vous-même dans la fonction install fournie.
  • Blockly fournira bientôt des outils qui vous permettront d'enregistrer des éléments déjà enregistrés sans erreur. En attendant, vous pouvez vérifier ce qui a déjà été enregistré avant d'enregistrer une extension, mutateur, mixin ou champ vous-même.
  • Indiquez clairement les conditions préalables ou les dépendances requises par vos définitions de plug-in ou de bloc.

• Envisagez de fournir des fonctions génératrices pour chacun des blocs que vous fournissez.

  • Fournir des fonctions de générateur prêtes à l'emploi permet aux utilisateurs d'utiliser plus facilement vos blocs sans avoir à comprendre leur structure et leur conception. S'ils doivent écrire leurs propres fonctions de générateur, cela peut entraîner un travail redondant de la part de chaque utilisateur.
  • JavaScript est le langage le plus utilisé dans Blockly, donc si vous choisissez un langage, nous vous recommandons d'utiliser JavaScript, sauf si vos blocs sont conçus pour un langage spécifique, par exemple pour implémenter une bibliothèque Python.
  • Envisager de publier un message d'aide de langues pour lesquelles vous n'est pas en mesure d'implémenter les fonctions de générateur ni d'accepter les demandes d'extraction pour si un utilisateur y contribue.

  • Si vous fournissez une fonction d'installation pour votre bloc, vous pouvez accepter une paramètre generators facultatif. Si un utilisateur transmet une instance de générateur que vous acceptez, vous pouvez installer automatiquement la fonction de générateur de code de bloc et effectuer des tâches associées, telles que l'ajout de mots réservés :

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.common.defineBlocks({my_custom_block: myCustomBlock});
        if (generators.javascript) {
          generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
          generators.javascript.addReservedWords('specialReservedWord');
        }
      }
    
      // How a user may install your block
      import {javascriptGenerator} from 'blockly/javascript';
      import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
      // installs the block definition and the javascript block-code generator
      installMyCustomBlock({javascript: javascriptGenerator});
    

Commentaires

Si vous avez des questions sur la meilleure façon de suivre ces consignes dans votre plug-in, n'hésitez pas à nous en faire part sur le forum. Nous aimerions voir vos bibliothèques de blocs et vous fournir des commentaires à leur sujet.

Notez que tous les plug-ins propriétaires qui fournissent des définitions de blocs ne respectent pas actuellement ces consignes, mais les nouveaux plug-ins le feront, et nous prévoyons de migrer les plug-ins existants.