Utiliser les API Blockly

Introduction

Cette page décrit les bonnes pratiques pour appeler des fonctions et accéder aux propriétés dans Blockly. Ces principes s'appliquent à la création de plug-ins pour Blockly ou à l'intégration de Blockly dans une application autonome.

Sous-classement et extension

Blockly utilise plusieurs paradigmes pour ajouter des fonctionnalités, y compris:

  • Sous-classes (par exemple, création d'un moteur de rendu)
  • Mixins (par exemple, ajout d'une extension de blocage ou d'un mutateur)
  • Définitions de blocs (ex. : définitions de blocs de procédure)

Pour les besoins de ce document, ces trois cas équivalent au sous-classement.

Injecter des sous-classes

Nous acceptons le remplacement de certaines classes via la méthode Blockly.inject. Ces sous-classes doivent soit étendre la classe de base, soit implémenter l'interface correspondante.

Vous pouvez transmettre votre sous-classe à la méthode d'injection.

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

Vous pouvez également enregistrer votre classe à l'aide de Blockly.registry et utiliser le nom du registre pour l'injecter. Cela est utile si vous stockez vos options d'injection au format JSON pur.

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}

Les classes suivantes peuvent être remplacées:

Nom enregistré Classe Interface/Base
blockDragger Blockly.IBlockDragger
connectionChecker Blockly.IConnectionChecker
connectionPreviewer Blockly.IConnectionPreviewer
flyoutsVerticalToolbox Blockly.IFlyout
flyoutsHorizontalToolbox Blockly.IFlyout
metricsManager Blockly.IMetricsManager
renderer Blockly.blockRendering.Renderer
toolbox Blockly.IToolbox

Pour en savoir plus sur l'utilisation des interfaces, consultez la section Interfaces de la documentation.

Visibilité

Nous utilisons des modificateurs d'accès TypeScript pour marquer la visibilité dans la bibliothèque principale en tant que public, private ou protected. Certaines propriétés peuvent être annotées avec @internal dans leurs commentaires TsDoc.

Toutes les propriétés public et protected sont documentées dans la section References (Références) du site Web de Blockly. Vous pouvez également vérifier la visibilité en lisant le code.

publique

Tout élément marqué public fait partie de notre API publique. Toute propriété d'un module qui n'a pas de modificateur de visibilité est considérée comme publique.

Nous essayons de ne pas modifier notre API publique fréquemment, sans raison valable ni avertissement. Exception: nous pouvons rendre une nouvelle API publique dans une version et la modifier dans la prochaine version en réponse aux premiers commentaires. Ensuite, vous pouvez considérer qu'une fonction publique ou une propriété est stable.

Les fonctions publiques peuvent être appelées depuis n'importe quel emplacement et remplacées dans des sous-classes tant que la signature ne change pas.

protégé

Les fonctions et propriétés protégées ne sont accessibles que par la classe qui la définit ou une sous-classe.

Les sous-classes sont autorisées à remplacer les fonctions et les propriétés protégées, sans modifier les signatures de type.

Par exemple, un moteur de rendu personnalisé qui étend la classe de moteur de rendu de base peut accéder à ses propriétés protégées.

Dans chaque cas, assurez-vous de bien comprendre comment la fonction ou la propriété est utilisée dans le reste du code.

private

Ils ne sont accessibles que par le code qui se trouve dans le même fichier que la définition. L'accès direct à ces propriétés peut entraîner un comportement indéfini.

Les sous-classes ne sont pas autorisées à remplacer des fonctions et des propriétés privées.

Les propriétés privées peuvent être modifiées sans préavis, car elles ne sont pas considérées comme faisant partie de l'API publique de Blockly.

Certaines fonctions de Blockly n'ont pas d'annotations de visibilité, car elles ne sont pas exportées depuis leur module. Ces fonctions sont essentiellement des variables locales et ne peuvent pas être utilisées en dehors de leur module de définition. Elles doivent être considérées comme l'équivalent des propriétés privées.

internal

Les fonctions et propriétés internes sont destinées à être utilisées dans la bibliothèque principale, mais pas en externe. Ils sont désignés par l'annotation TsDoc @internal.

Les propriétés internes peuvent être modifiées sans préavis, car elles ne sont pas considérées comme faisant partie de l'API publique de Blockly.

Les propriétés internes sont accessibles depuis n'importe où dans le noyau et sont remplacées dans les sous-classes du cœur tant que la signature ne change pas. Ils ne doivent pas être accessibles en dehors de la bibliothèque principale.

obsolète

Aucun élément comportant la valeur @deprecated ne doit être utilisé. La plupart des abandons incluent des instructions sur le code préféré, soit dans un avertissement de la console, soit dans un TSDoc.

Dans la mesure du possible, les fonctions obsolètes génèrent un avertissement indiquant la date de suppression souhaitée et une recommandation concernant l'appel d'une fonction de remplacement.

Questions fréquentes

Que faire si la fonction que je souhaite utiliser n'est pas publique ?

Envoyez une demande de fonctionnalité sur Corely Blockly. Incluez une description de votre cas d'utilisation et précisez ce que vous souhaitez rendre public.

Nous utiliserons cette fonctionnalité pour demander si vous souhaitez la rendre publique ou s'il existe d'autres moyens d'obtenir les mêmes informations.

Si nous décidons de la rendre publique, vous ou l'équipe Blockly apporterez la modification appropriée. Elle sera appliquée dans la prochaine version de Blockly.

Si vous choisissez d'utiliser un membre non public dans un plug-in, envisagez de le marquer comme version bêta et d'inclure les informations dans votre README.

Qu'en est-il de monkeypatching ?

En savoir plus sur monkeypatching

Monkeypatching est dangereux, car les correctifs peuvent cesser de fonctionner sans préavis en raison de l'utilisation d'éléments non publics de l'API Blockly. L'application de correctifs dans un plug-in est particulièrement dangereuse, car votre code peut interagir mal avec tout autre plug-in qui corrige le même code par monkeypatch. C'est pourquoi nous vous déconseillons vivement de l'utilisation de monkeypatch dans les applications et les plug-ins tiers, et nous ne l'accepterons pas dans les plug-ins propriétaires.

Puis-je ignorer les fonctions publiques ?

Lors du sous-classement: oui. Sinon, non, c'est monkeypatching.

Puis-je ignorer des fonctions protégées ?

Lors du sous-classement: oui. Sinon, non, c'est monkeypatching.

Puis-je remplacer des fonctions internes ou privées ?

Non, c'est monkeypatch.

Quand pourrai-je accéder directement aux propriétés ? Quand dois-je utiliser un getter ou un setter ?

Si nous publions un getter ou un setter, veuillez l'utiliser au lieu d'accéder directement à la propriété. Si la propriété n'est pas publique, utilisez des getters et des setters.

Que se passe-t-il si une propriété ne comporte pas d'annotation ?

Par défaut, elle est publique, mais n'hésitez pas à nous envoyer une ligne au cas où nous voudrions mettre en place une paire getter/setter pour vous.

Que se passe-t-il si une fonction ne comporte pas d'annotation ?

Par défaut, il est public.

Que faire si je ne sais toujours pas ?

Posez une question sur le forum et nous vous répondrons, généralement dans un délai d'un jour ouvré.