En esta página, se describen las prácticas recomendadas para llamar a funciones y acceder a propiedades en Blockly principal. Estos principios se aplican a la creación de complementos para Blockly o a la integración de Blockly en una aplicación independiente.
Visibilidad
Usamos modificadores de acceso de TypeScript para marcar la visibilidad en la biblioteca principal como public, private o protected.
Algunas propiedades se pueden anotar con @internal en sus comentarios de TsDoc.
Todas las propiedades public y protected se documentan en la sección Referencias del sitio web de Blockly. También puedes verificar la visibilidad leyendo el código.
Pública
Todo lo que esté marcado como public forma parte de nuestra API pública. Cualquier propiedad de un módulo que no tenga un modificador de visibilidad se considera pública.
Intentamos no cambiar nuestra API pública con frecuencia o sin un motivo y una advertencia apropiados. La excepción: Es posible que publiquemos una API nueva en una versión y la modifiquemos en la siguiente en respuesta a los primeros comentarios. Después de eso, puedes considerar que una función o propiedad pública es estable.
Se puede llamar a las funciones públicas desde cualquier lugar y anularlas en subclases, siempre que la firma no cambie.
protegidos
Solo la clase de definición o una subclase pueden acceder a las funciones y propiedades protegidas.
Las subclases pueden anular funciones y propiedades protegidas sin cambiar las firmas de tipo.
Por ejemplo, un renderizador personalizado que extiende la clase de renderizador base puede acceder a sus propiedades protegidas.
En cada caso, debes asegurarte de comprender cómo se usa la función o la propiedad en el resto del código.
privado
Solo se puede acceder a ellas mediante código en el mismo archivo que la definición. Si accedes directamente a estas propiedades, es posible que se genere un comportamiento indefinido.
Las subclases no pueden anular funciones ni propiedades privadas.
Las propiedades privadas están sujetas a cambios sin advertencia, ya que no se consideran parte de la API pública de Blockly.
Algunas funciones de Blockly no tienen anotaciones de visibilidad porque no se exportan desde su módulo. Estas funciones son, en esencia, variables locales y no se pueden usar fuera de su módulo de definición. Se deben considerar equivalentes a las propiedades privadas.
interno
Las funciones y propiedades internas están diseñadas para usarse dentro de la biblioteca principal, pero no de forma externa. Se designan con la anotación @internal de TsDoc.
Las propiedades internas están sujetas a cambios sin previo aviso, ya que no se consideran parte de la API pública de Blockly.
Se puede acceder a las propiedades internas desde cualquier lugar del núcleo y anularse en las subclases del núcleo, siempre y cuando la firma no cambie. No se debe acceder a ellos desde fuera de la biblioteca principal.
obsoleto
No se debe usar nada marcado como @deprecated. La mayoría de las bajas incluyen instrucciones sobre el código preferido, ya sea en una advertencia de la consola o en TSDoc.
Siempre que sea posible, las funciones obsoletas registrarán una advertencia que incluya la fecha de eliminación prevista y una recomendación para llamar a una función de reemplazo.
Preguntas frecuentes
Las siguientes son algunas preguntas frecuentes que el equipo de Blockly encontró.
¿Qué sucede si la función que quiero usar no es pública?
Envía una solicitud de función en Blockly principal. Incluye una descripción de tu caso de uso y una declaración de lo que te gustaría que divulguemos.
Usaremos la función para solicitar que hablemos sobre si publicarlo o si hay otras formas de obtener la misma información.
Si decidimos hacerlo público, tú o el equipo de Blockly realizarán el cambio correspondiente, y se publicará en la próxima versión de Blockly.
Si decides usar un miembro no público en un complemento, considera marcarlo como una versión beta y, luego, incluye la información en tu README.
¿Qué sucede con el monkeypatching?
Obtén más información sobre el parcheo de mono.
El monkeypatching no es seguro, ya que los parches podrían dejar de funcionar sin previo aviso debido al uso de elementos no públicos de la API de Blockly. Aplicar parches en un complemento es especialmente peligroso, ya que tu código puede interactuar de forma deficiente con cualquier otro complemento que aplique parches al mismo código. Por este motivo, recomendamos que no uses el monkeypatching en aplicaciones ni complementos de terceros, y no lo aceptaremos en complementos propios.
¿Puedo anular las funciones públicas?
Cuando se crea una subclase: sí. De lo contrario, no, eso es un parche.
¿Puedo anular funciones protegidas?
Cuando se crea una subclase: sí. De lo contrario, no, eso es un parche.
¿Puedo anular funciones internas o privadas?
No, eso es un parche.
¿Cuándo puedo acceder a las propiedades directamente? ¿Cuándo debo usar un método get o set?
Si publicamos un método get o set, úsalos en lugar de acceder directamente a la propiedad. Si la propiedad no es pública, usa los métodos get y set.
¿Qué sucede si una propiedad no tiene una anotación?
De forma predeterminada, es público, pero escríbenos si quieres que implementemos un par de métodos get/set.
¿Qué sucede si una función no tiene una anotación?
Es pública de forma predeterminada.
¿Qué sucede si aún no estoy seguro?
Haz una pregunta en el foro y nos comunicaremos contigo en unos días.