Introducción
En esta página, se describen las prácticas recomendadas para llamar a funciones y acceder en Blockly. Estos principios se aplican a la creación de complementos para Blockly o una integración de Blockly en una aplicación independiente
Subclasificación y extensión
Blockly tiene varios paradigmas para agregar funcionalidad, incluidos los siguientes:
- Subclases (p.ej., crear un procesador nuevo)
- Mixins (p.ej., agregar una extensión de bloque o un mutador)
- Definiciones de bloque (p.ej., definiciones de bloque de procedimiento)
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. Estos
las subclases deben extender la clase base o implementar su respectivo
interfaz de usuario.
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 la
de registro para insertar la clase. Esto es útil si almacena la 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 cómo usar las interfaces, consulta la sección Interfaces. de la documentación.
Visibilidad
Usamos los 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 su
Comentarios de TsDoc.
Todas las propiedades public y protected se documentan en el
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úblico.
Tratamos de no cambiar nuestra API pública con frecuencia o sin un buen motivo y advertencia. La excepción es que podemos hacer pública una nueva API en una versión y y modificarla en la próxima versión como respuesta a los comentarios anticipados. Luego, podrás consideran una función pública o propiedad estable.
Las funciones públicas se pueden llamar desde cualquier lugar y se pueden anular en las subclases, como siempre que la firma no cambie.
protegido
Solo se puede acceder a las funciones y propiedades protegidas a través de la clase o una subclase.
Las subclases pueden anular funciones y propiedades protegidas, sin cambiar las firmas de tipos.
Por ejemplo, un procesador personalizado que extiende la clase de procesador base puede acceder sus propiedades protegidas.
En cada caso, debes asegurarte de comprender cómo se desempeña la función se usa en el resto del código.
privado
Solo se puede acceder a ellas mediante el código que se encuentra en el mismo archivo que la definición. Directamente el acceso 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 lo están considera parte de la API pública de Blockly.
Algunas funciones de Blockly no tienen anotaciones de visibilidad porque son no se exportan de su módulo. Estas funciones son variables locales y no se puede usar fuera del módulo que lo define. Deben considerarse equivalentes a las propiedades privadas.
interno
Las funciones y propiedades internas están diseñadas para usarse dentro del núcleo.
biblioteca, pero no externamente. Se los designa con el TsDoc @internal.
.
Las propiedades internas están sujetas a cambios sin advertencia, ya que no lo son considera parte de la API pública de Blockly.
Se puede acceder a las propiedades internas desde cualquier lugar del núcleo y se anulan subclases en Core, siempre que la firma no cambie. No deben ser a la que se accede 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 del código preferido, ya sea en una advertencia de la consola o en un TSDoc.
Cuando sea posible, las funciones obsoletas registrarán una advertencia con el 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?
Presentar una solicitud de función en Blockly. Incluye una descripción de tu caso de uso y una declaración de qué que quieres que hagamos públicas.
Usaremos la función para solicitar decidir si hacerla pública o si hay otras formas de obtener la misma información.
Si decidimos hacerlo público, tú o el equipo de Blockly harán el cambio y se publicará en el próximo lanzamiento de Blockly.
Si decides usar un miembro no público en un complemento, considera marcar tu
como beta e incluir la información en tu README.
¿Y qué pasa con los parches de mono?
Obtén más información sobre monkeypatching.
Monkeypatching no es seguro porque los parches podrían dejar de funcionar sin previo aviso debido a a usar partes no públicas de la API de Blockly. La aplicación de parches en un complemento especialmente peligroso, ya que tu código puede interactuar mal con cualquier otro que aplica monkeypatch el mismo código. Por este motivo, destamos recomendarles no monkeypatching en aplicaciones y complementos de terceros, y no la aceptará en complementos propios.
¿Puedo anular las funciones públicas?
Cuando se hace la subclasificación: sí. De lo contrario, no, eso es un parche de mono.
¿Puedo anular funciones protegidas?
Cuando se hace la subclasificación: sí. De lo contrario, no, eso es un parche de mono.
¿Puedo anular funciones internas o privadas?
No, eso es un parche de mono.
¿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 hacerlo directamente antes de acceder a ella. Si la propiedad no es pública, usa métodos get. y métodos set.
¿Qué sucede si una propiedad no tiene una anotación?
Por defecto, es público, pero envíanos una línea por si quieres que par get y set para ti.
¿Qué sucede si una función no tiene una anotación?
Es público de forma predeterminada.
¿Qué sucede si aún no lo sé?
Haz una pregunta en el foro. y nos comunicaremos contigo, generalmente, en un plazo de un día hábil.