Plug-ins

Introduction

Un plug-in est un extrait de code autonome qui ajoute des fonctionnalités à Blockly. Ils permettent d'ajouter des champs, de définir des thèmes, de créer des moteurs de rendu, et bien plus encore.

L'utilisateur cible d'un plug-in est un développeur qui trouve et utilise le plug-in via npm. Pour en savoir plus sur la création d'un plug-in, vous pouvez également regarder notre vidéo 2021 How to Build a Plugin Talk et notre présentation 2021 des plug-ins.

Propriétaires et tiers

Les plug-ins définis dans le dépôt blockly-samples sont des plug-ins propriétaires, ce qui signifie qu'ils sont compatibles avec l'équipe Blockly et publiés sous le champ d'application @blockly sur npm.

Plug-ins propriétaires performants:

  • présentent des cas d'utilisation évidents,
  • sont à usage général
  • sont stables ;
  • sont faciles à utiliser ;

Les plug-ins tiers sont gérés et publiés indépendamment. Les plug-ins tiers peuvent être plus complexes, plus expérimentaux ou plus ciblés.

Par exemple, un champ permettant de définir la vitesse du moteur peut être utilisé dans de nombreux projets de robotique. D'autre part, un champ permettant de modifier un objet spécifique défini par le schéma de votre base de données est préférable en tant que plug-in tiers.

Critères propriétaires

Les plug-ins propriétaires doivent répondre aux exigences suivantes:

  • Fonctionne sur toutes les grandes plates-formes, sauf en cas d'exception accordée par l'équipe Blockly.
    • Chrome, Firefox, Safari, Edge
  • L'auteur est prêt à gérer des bugs pendant la première année.
  • N'est pas monkeypatch Blockly.
  • Possède une API clairement définie et documentée.
  • N'appelle pas des fonctions privées ou de package depuis Blockly Core, sauf en cas d'exception accordée par l'équipe Blockly.
    • Le remplacement des fonctions de package sur une sous-classe que vous définissez est autorisé.
    • Si vous souhaitez bénéficier d'une exception, contactez-nous au sujet d'un problème concernant blockly-samples.
  • Comporte des tests.

Rechercher des plug-ins

  • Sur les pages GitHub Découvrez des démonstrations en direct de plug-ins propriétaires.
  • Sur npm : recherchez @blockly pour afficher la liste des plug-ins publiés par l'équipe Blockly.
  • Sur GitHub, consultez le répertoire des plug-ins dans le dépôt blockly-samples. Chaque plug-in possède un fichier README qui décrit son comportement et son utilisation prévue.

Installer des plug-ins

  1. Recherchez le plug-in que vous souhaitez installer à l'aide de l'une des ressources ci-dessus et localisez le fichier README.

  2. Suivez les instructions d'installation contenues dans le fichier README. En général, vous devez installer le plug-in depuis npm, par exemple

    npm install @blockly/block-plus-minus --save

    et l'importer dans votre code (ex. :

    import Blockly from 'blockly';
import '@blockly/block-plus-minus';

  3. Certains plug-ins peuvent nécessiter des étapes supplémentaires, telles que l'initialisation ou l'enregistrement du plug-in. Ces étapes sont indiquées dans le fichier README.

Versions du plug-in

Les plug-ins de blockly-samples suivent la gestion sémantique des versions. Toutes les modifications destructives seront donc incluses dans une nouvelle version majeure. Tout nouveau plug-in qui repose sur l'outil Monkey Patching Core sera associé à la version majeure 0 pour signifier le développement initial, comme indiqué dans la spécification semver.

La plupart des plug-ins incluent le package blockly principal en tant que peerDependency plutôt qu'en tant que dépendance. En effet, nous nous attendons à ce que vous ayez déjà installé Blockly vous-même dans votre propre application (il ne serait pas logique d'utiliser un plug-in sans utiliser également Blockly) et que vous puissiez gérer vous-même la version de Blockly. Cependant, de nombreux plug-ins sont développés pour utiliser les nouvelles API disponibles dans la version la plus récente de Blockly. Vous devez donc connaître les exigences de version. L'package.json du plug-in vous indique quelle est la version minimale de Blockly compatible avec ce plug-in. Si un plug-in est mis à jour pour nécessiter une version plus récente de Blockly, par exemple pour bénéficier d'une toute nouvelle API, la version majeure du plug-in sera augmentée, car nous considérons qu'il s'agit d'une modification destructive.

Lorsque vous ajoutez le plug-in à votre package.json, la valeur par défaut consiste à inclure un accent circonflexe avant la version, par exemple :

"@blockly/block-plus-minus": "^2.0.15"

Cela permettra à npm d'installer n'importe quelle version mineure supérieure ou égale à la version répertoriée, de sorte que la version 2.0.20 ou 2.1.0 puisse fonctionner, mais pas une nouvelle version majeure telle que 3.0.1. Lorsque vous effectuez une mise à jour vers une nouvelle version de Blockly, nous vous recommandons de vérifier si l'un de vos plug-ins peut également être mis à jour vers une nouvelle version majeure.

Installer des plug-ins sans npm

Bien que nous recommandions généralement d'utiliser npm pour recevoir facilement les mises à jour, il est possible d'utiliser des plug-ins sans npm.

Vous pouvez utiliser unpkg pour inclure les fichiers du plug-in sans les cloner, par exemple

<script src="https://unpkg.com/@blockly/block-plus-minus"></script>

Vous pouvez également cloner le dépôt blockly-samples et inclure les fichiers localement, comme si vous aviez cloné Blockly. Toutefois, nous vous recommandons d'utiliser un gestionnaire de packages si possible, car cela vous aidera à rester à jour avec les dernières fonctionnalités et corrections de bugs du plug-in.

Avec cette méthode, vous devrez toujours suivre les étapes d'initialisation ou d'enregistrement répertoriées dans le fichier README du plug-in.