Cette page décrit les bonnes pratiques à suivre pour appeler des fonctions et accéder aux propriétés dans Blockly de base. Ces principes s'appliquent à la création de plug-ins pour Blockly ou à l'intégration de Blockly dans une application autonome.
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 leurs commentaires TsDoc.
Toutes les propriétés public et protected sont documentées dans la 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 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 version suivante en réponse aux premiers commentaires. Vous pouvez ensuite considérer une fonction ou une propriété publique comme stable.
Les fonctions publiques peuvent être appelées de n'importe où et remplacées dans les sous-classes tant que la signature ne change pas.
protégées
Les fonctions et propriétés protégées ne peuvent être accessibles que par la classe définissante 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, vous devez vous assurer de comprendre comment la fonction ou la propriété est utilisée dans le reste du code.
privé
Elles ne sont accessibles qu'au code du 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 avertissement, car elles ne font pas partie de l'API publique de Blockly.
Certaines fonctions de Blockly ne comportent 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 équivalentes aux propriétés privées.
interne
Les fonctions et propriétés internes sont destinées à être utilisées dans la bibliothèque principale, mais pas en externe. Elles sont désignées par l'annotation @internal TsDoc.
Les propriétés internes sont susceptibles d'être modifiées sans avertissement, car elles ne font pas partie de l'API publique de Blockly.
Les propriétés internes peuvent être accessibles depuis n'importe quel point du noyau et remplacées dans les sous-classes du noyau tant que la signature ne change pas. Elles ne doivent pas être accessibles en dehors de la bibliothèque principale.
obsolète
Tout élément marqué @deprecated ne doit pas être utilisé. La plupart des abandons incluent des instructions sur le code à privilégier, soit dans un avertissement de la console, soit dans un TSDoc.
Dans la mesure du possible, les fonctions obsolètes enregistrent un avertissement qui inclut la date de suppression prévue et une recommandation de fonction de remplacement à appeler.
Questions fréquentes
Vous trouverez ci-dessous quelques questions fréquentes que l'équipe Blockly a rencontrées.
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 indiquez ce que vous souhaitez que nous rendions public.
Nous utiliserons cette fonctionnalité pour vous demander si vous souhaitez la rendre publique ou si vous avez 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, 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, envisagez de marquer votre plug-in comme version bêta et d'inclure les informations dans votre README.
Qu'en est-il du monkey-patching ?
En savoir plus sur le monkeypatching
Le monkey patching n'est pas sécurisé, car les correctifs peuvent cesser de fonctionner sans préavis en raison de l'utilisation de composants non publics de l'API Blockly. Le patch dans un plug-in est particulièrement dangereux, car votre code peut interagir de manière inappropriée avec tout autre plug-in qui modifie le même code. C'est pourquoi nous vous recommandons vivement de ne pas utiliser le monkey-patching dans les applications et les plug-ins tiers, et nous ne l'accepterons pas dans les plug-ins propriétaires.
Puis-je remplacer des fonctions publiques ?
Lors du sous-classement: oui. Sinon, non, c'est du monkey-patching.
Puis-je remplacer des fonctions protégées ?
Lors du sous-classement: oui. Sinon, non, c'est du monkey-patching.
Puis-je remplacer des fonctions internes ou privées ?
Non, c'est du monkey-patching.
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 impérativement des getters et des setters.
Que faire si une propriété n'est pas associée à une annotation ?
Par défaut, il est public, mais veuillez nous envoyer un message si vous souhaitez que nous mettions en place une paire getter/setter.
Que se passe-t-il si une fonction n'a pas d'annotation ?
Il est public par défaut.
Que faire si je ne suis toujours pas sûr ?
Posez-nous une question sur le forum, et nous vous recontacterons dans quelques jours.