Introduction
Cette page décrit les bonnes pratiques pour appeler des fonctions et accéder dans les applications de base de 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 propose 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 bloc ou d'un mutateur)
- Définitions de blocs (ex. : définitions de blocs de procédure)
Aux fins du présent document, les trois cas équivalent à sous-classement.
Injecter des sous-classes
Il est possible de remplacer certaines classes via la méthode Blockly.inject. Ces
les sous-classes doivent soit étendre la classe de base, soit implémenter la classe
de commande.
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 la
nom du registre pour injecter la classe. Cela est utile si vous stockez votre code
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 plus d'informations 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 comme public, private ou protected.
Certaines propriétés peuvent être annotées avec @internal dans leur
Commentaires TsDoc.
Toutes les propriétés public et protected sont documentées dans le
Section Références du site Web 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 ne comporte pas de modificateur de visibilité est considérée comme publique.
Nous nous efforçons de ne pas modifier notre API publique fréquemment ou sans raison valable. avertissement. Exception: nous pouvons rendre une nouvelle API publique dans une seule version et le modifier dans la prochaine version en réponse aux premiers commentaires. Vous pourrez ensuite comme une fonction ou une propriété publique stable.
Les fonctions publiques peuvent être appelées depuis n'importe où et remplacées dans les sous-classes en tant que tant que la signature ne change pas.
protégé
Seul la classe définissant ou une sous-classe.
Les sous-classes sont autorisées à remplacer les fonctions et propriétés protégées, sans la modification des signatures de type.
Par exemple, un moteur de rendu personnalisé qui étend la classe du 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é utilisée dans le reste du code.
privé
Ceux-ci ne sont accessibles que par le code situé dans le fichier correspondant à la définition. Directement l'accès à ces propriétés peut entraîner un comportement non défini.
Les sous-classes ne sont pas autorisées à remplacer les fonctions et propriétés privées.
Les propriétés privées sont susceptibles d'être modifiées sans avertissement, car elles ne le sont pas comme faisant partie de l'API publique de Blockly.
Certaines fonctions de Blockly n'ont pas d'annotations de visibilité, car elles sont non exportés de leur module. Ces fonctions sont essentiellement des variables locales et ne peuvent pas être utilisées en dehors de leur module de définition. Ils doivent être pris en compte équivalentes aux propriétés privées.
interne
Les fonctions et propriétés internes sont destinées à être utilisées dans le
bibliothèque, mais pas en externe. Elles sont désignées par le TsDoc @internal.
.
Les propriétés internes sont susceptibles d'être modifiées sans avertissement, car elles ne le sont pas comme faisant partie de l'API publique de Blockly.
Les propriétés internes sont accessibles depuis n'importe où dans la suite principale et remplacées dans sous-jacentes dans le noyau tant que la signature ne change pas. Elles ne doivent pas être accessibles depuis l'extérieur de la bibliothèque principale.
obsolète
Aucun élément marqué @deprecated ne doit être utilisé. La plupart des abandons incluent
des instructions sur le code de préférence, soit dans un avertissement de la console, soit dans un TSDoc.
Lorsque cela est possible, les fonctions obsolètes génèrent un avertissement qui inclut le paramètre la date de suppression prévue et la recommandation d'appeler une fonction de remplacement.
Questions fréquentes
Que faire si la fonction que je souhaite utiliser n'est pas publique ?
Envoyer une demande de fonctionnalité sur Blockly. Incluez une description de votre cas d'utilisation et un énoncé de que vous souhaitez rendre publics.
Nous utiliserons cette fonctionnalité pour demander à discuter de la rendre publique ou non. 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 modification appropriée, et elle sera mise en ligne dans la prochaine version de Blockly.
Si vous choisissez d'utiliser un membre non public dans un plug-in, pensez à marquer votre
en version bêta et incluez les informations dans votre README.
Qu'en est-il du "monkeypatching" ?
Consultez monkeypatching pour en savoir plus.
Monkeypatching est dangereux, car les correctifs peuvent cesser de fonctionner sans préavis en raison à l'utilisation d'éléments non publics de l'API Blockly. L'application de correctifs dans un plug-in est ce qui est particulièrement dangereux, car votre code peut mal interagir avec d'autres qui permet à monkeypatch d'appliquer le même code. C'est pourquoi nous mettons vivement recommandent de ne pas utiliser "monkeypatching" dans les applications et les plug-ins tiers ; ne l'accepteront pas dans les plug-ins propriétaires.
Puis-je ignorer les fonctions publiques ?
Lors du sous-classement: oui. Dans le cas contraire: non, il s'agit de monkeypatching.
Puis-je ignorer des fonctions protégées ?
Lors du sous-classement: oui. Dans le cas contraire: non, il s'agit de monkeypatching.
Puis-je ignorer les fonctions internes ou privées ?
Non, c'est monkeypatching.
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 de qui accèdent à la propriété. Si la propriété n'est pas publique, utilisez absolument des getters et setters.
Que se passe-t-il si une propriété n'a pas d'annotation ?
Par défaut, il est public, mais n'hésitez pas à nous écrire si nous voulons ajouter un getter/setter en place pour vous.
Que se passe-t-il si une fonction n'a pas d'annotation ?
Par défaut, il est public.
Que faire si je ne sais toujours pas ?
Poser une question sur le forum et nous y répondrons dans un délai d'un jour ouvré.