Usa las API de Blockly

Introducción

En esta página, se describen las prácticas recomendadas para llamar a funciones y acceder a las propiedades del núcleo de Blockly. Estos principios se aplican a la creación de complementos para Blockly o a la integración de Blockly en una aplicación independiente.

Subclasificación y extensión

Blockly tiene varios paradigmas para agregar funcionalidades, como los siguientes:

• Subclases (p.ej., creación de un procesador nuevo)
• Mixins (p.ej., agregar una extensión de bloque o un mutador)
• Definiciones de bloqueos (p.ej., definiciones de bloques de procedimientos)

A los efectos de este documento, los tres casos son equivalentes a la subclasificación.

Cómo insertar subclases

Admitimos el reemplazo de ciertas clases a través del método Blockly.inject. Estas subclases deben extender la clase base o implementar su interfaz correspondiente.

Puedes pasar tu subclase al método de inserción.

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

También puedes registrar tu clase con Blockly.registry y usar el nombre de registro para insertarla. Esto es útil si almacenas tus opciones de inyección como JSON puro.

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

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

Se pueden reemplazar las siguientes clases:

Nombre de registro	Interfaz/clase 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

Para obtener más información sobre el uso de interfaces, consulta la sección de interfaces de la documentación.

Nota: Se pueden anular todos los métodos protegidos y públicos en clases registradas. Sin embargo, no se deben anular los métodos protegidos en clases no registradas.

Visibilidad

Usamos modificadores de acceso de TypeScript para marcar la visibilidad en la biblioteca principal como public, private o protected. Algunas propiedades pueden tener anotaciones con @internal en sus comentarios 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.

Precaución: Si bien JavaScript no aplica de manera forzosa estas anotaciones de visibilidad, debes evitar acceder a elementos que no sean public. El equipo de Blockly no garantiza la estabilidad de las propiedades y funciones no públicas entre las versiones.

Pública

Todo lo que esté marcado como public es 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 buen motivo y advertencia. Excepción: Es posible que hagamos pública una nueva API en una versión y la modifiquemos en la próxima en respuesta a los comentarios anticipados. Luego, puedes considerar que una función pública o una propiedad sean estables.

Las funciones públicas se pueden llamar desde cualquier lugar y anularse en subclases, siempre que la firma no cambie.

protegido

Solo se puede acceder a las funciones y propiedades protegidas mediante la clase de definición o una subclase.

Las subclases pueden anular funciones y propiedades protegidas sin cambiar las firmas de tipo.

Por ejemplo, un procesador personalizado que extiende la clase de procesador base puede acceder a sus propiedades protegidas.

En cada caso, debes asegurarte de comprender cómo se usa la función o propiedad en el resto del código.

private

Solo se puede acceder a ellas con el código del mismo archivo que la definición. El acceso directo a estas propiedades puede dar como resultado un comportamiento indefinido.

Las subclases no pueden anular funciones y 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. En esencia, estas funciones son variables locales y no pueden usarse fuera del módulo que las define. Se deben considerar equivalentes a las propiedades privadas.

Nota: Anteriormente, Blockly usaba un guion bajo para indicar propiedades privadas: example_. De acuerdo con la guía de estilo actual de Google, ya no hacemos esto en código nuevo y es posible que cambiemos el código antiguo. Antes de llamar a un método en Blockly, asegúrate de que aparezca en la documentación de referencia o que no esté marcado como privado en el código. En casos excepcionales, las funciones privadas se usaron tanto que se volvieron públicas, por lo que es posible que veas funciones públicas que terminan en guion bajo.

internas

Las funciones y propiedades internas están diseñadas para usarse dentro de la biblioteca principal, pero no externamente. Se designan con la anotación @internal de TsDoc.

Las propiedades internas están sujetas a cambios sin advertencia, ya que no se consideran parte de la API pública de Blockly.

Se puede acceder a las propiedades internas desde cualquier lugar dentro del núcleo y se pueden anular en las subclases del núcleo siempre que la firma no cambie. No se debe acceder a ellas desde fuera de la biblioteca principal.

obsoleto

No se debe usar ningún elemento marcado como @deprecated. La mayoría de las bajas incluyen instrucciones en el código preferido, ya sea en una advertencia de la consola o en TSDoc.

Cuando 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

¿Qué sucede si la función que quiero usar no es pública?

Envía una solicitud de función en el núcleo de Blockly. Incluye una descripción de tu caso de uso y una declaración de lo que quieres que hagamos público.

Usaremos la función para solicitar información sobre si la haremos pública o si existen otras maneras de obtener la misma información.

Si decidimos publicarlo, tanto tú como el equipo de Blockly harán el cambio correspondiente, que se publicará en la próxima versión de Blockly.

Si decides usar un miembro no público en un complemento, considera marcar tu complemento como versión beta y, luego, incluye la información en tu README.

¿Qué pasa con monkeypatching?

Obtén más información sobre monkeypatching.

Monkeypatching no es seguro, ya que los parches podrían dejar de funcionar sin previo aviso debido al uso de partes no públicas de la API de Blockly. Aplicar parches en un complemento es especialmente peligroso, ya que tu código puede interactuar mal con cualquier otro complemento en el que se aplique el mismo código con monkeypatch. Por este motivo, recomendamos no aplicar monkeypatch en aplicaciones y complementos de terceros, y no aceptarlo en complementos propios.

¿Puedo anular funciones públicas?

Cuando se crean subclases: sí. De lo contrario, no, eso es monkeypatching.

¿Puedo anular funciones protegidas?

Cuando se crean subclases: sí. De lo contrario, no, eso es monkeypatching.

¿Puedo anular funciones internas o privadas?

No, eso es monkeypatching.

¿Cuándo puedo acceder a las propiedades directamente? ¿Cuándo debo usar un método get o un método set?

Si publicamos un método get o un método set, úsala en lugar de acceder directamente a la propiedad. Si la propiedad no es pública, definitivamente debes usar métodos get y set.

Nota: El uso coherente de métodos get y set en los complementos nos brinda flexibilidad para realizar cambios en el núcleo de Blockly sin romper el código publicado.

¿Qué sucede si una propiedad no tiene anotación?

De forma predeterminada, es público, pero escríbenos por si queremos poner un par de métodos get y set por ti.

¿Qué pasa si una función no tiene una anotación?

Es público de forma predeterminada.

¿Qué puedo hacer si aún no tengo certeza?

Haz una pregunta en el foro y nos comunicaremos contigo, generalmente en un día hábil.