Complementos

Introducción

Un complemento es un fragmento de código autónomo que agrega funcionalidad a Blockly. Los complementos pueden agregar campos, definir temas, crear representadores y mucho más.

El usuario objetivo de un complemento es un desarrollador que lo encuentra y lo usa a través de npm. Para obtener más información sobre la compilación de un complemento, también puedes mirar nuestra charla Cómo compilar un complemento de 2021 y nuestra charla de descripción general de complementos de 2021.

Propios frente a terceros

Los complementos definidos en el repositorio blockly-samples son los propios, lo que significa que son compatibles con el equipo de Blockly y se publican bajo el permiso @blockly de npm.

Excelentes complementos propios:

  • casos de uso evidentes
  • son de uso general
  • son estables
  • son fáciles de usar.

Los complementos de terceros se mantienen y publican de forma independiente. Los complementos de terceros pueden ser más complejos, experimentales o más segmentados.

Por ejemplo, un campo para establecer la velocidad del motor podría usarse en muchos proyectos de robótica. Por otro lado, un campo para editar un objeto específico definido por el esquema de la base de datos es mejor como complemento de terceros.

Criterios propios

Los complementos propios deben cumplir con estos requisitos:

  • Funciona en todas las plataformas principales, a menos que el equipo de Blockly te otorgue una exención.
    • Chrome, Firefox, Safari y Edge
  • Tiene un autor que está dispuesto a manejar errores durante el primer año.
  • No se aplica monkeypatch a Blockly.
  • Tiene una API claramente definida y documentada.
  • No llama a las funciones privadas ni a las funciones de paquetes desde el núcleo de Blockly, a menos que el equipo de Blockly les otorgue una exención.
    • Se permite anular funciones de paquetes en una subclase que definas.
    • Si quieres una exención, pregúntanos si tienes un problema con muestras bloqueadas.
  • Tiene pruebas.

Cómo buscar complementos

  • En las páginas de GitHub Explora las demostraciones en vivo de complementos propios.
  • En npm, busca @blockly para ver una lista de los complementos que publicó el equipo de Blockly.
  • En GitHub, consulta el directorio de complementos en el repositorio de muestras en bloque. Cada complemento tiene un archivo README que describe su comportamiento y uso previsto.

Instala complementos

  1. Busca el complemento que deseas instalar mediante uno de los recursos anteriores y ubica el archivo README.

  2. Sigue las instrucciones de instalación del archivo README. En general, deberás instalar el complemento desde npm; p.ej.,

    npm install @blockly/block-plus-minus --save

    e importarlo en tu código, p.ej.,

    import Blockly from 'blockly';
import '@blockly/block-plus-minus';

  3. Algunos complementos pueden requerir pasos adicionales, como inicializar o registrar el complemento. Estos pasos se enumerarán en el archivo README.

Versiones del complemento

Los complementos de las muestras en bloque siguen el control de versiones semántico, por lo que cualquier cambio rotundo se realizará en una versión principal nueva. Cualquier complemento nuevo que se base en el núcleo de aplicación de parches de monkey tendrá una versión principal de 0 para indicar el desarrollo inicial, como se indica en la especificación de semver.

La mayoría de los complementos incluyen el paquete blockly principal como parDependency en lugar de una dependencia. Esto se debe a que se espera que ya hayas instalado Blockly en tu propia aplicación (no tendría sentido usar un complemento sin también usar Blockly) y para que puedas administrar la versión de Blockly por tu cuenta. Sin embargo, muchos complementos se desarrollan para usar las nuevas APIs que se encuentran en la versión más reciente de Blockly, por lo que debes conocer los requisitos de la versión. El package.json del complemento te indicará cuál es la versión mínima de Blockly compatible con ese complemento. Si se actualiza un complemento para que necesite una versión más reciente de Blockly, p.ej., para aprovechar una API nueva, la versión principal del complemento aumentará, ya que lo consideramos un cambio rotundo.

Cuando agregas el complemento a tu package.json, la opción predeterminada es incluir un signo de intercalación antes de la versión, como

"@blockly/block-plus-minus": "^2.0.15"

Esto permitirá que npm instale cualquier versión secundaria en la lista o una posterior, por lo que podrían funcionar las versiones 2.0.20 o 2.1.0, pero no una versión principal nueva, como 3.0.1. Cuando actualices a una nueva versión de Blockly, te recomendamos que verifiques si alguno de tus complementos también se pudo actualizar a una nueva versión principal.

Instala complementos sin npm

Si bien generalmente recomendamos usar npm para recibir actualizaciones con facilidad, es posible usar complementos sin npm.

Podrías usar unpkg para incluir los archivos del complemento sin clonarlos, p.ej.,

<script src="https://unpkg.com/@blockly/block-plus-minus"></script>

También puedes clonar el repositorio blockly-samples e incluir los archivos de forma local de manera similar a como lo harías si hubieras clonado Blockly. Sin embargo, te recomendamos que uses un administrador de paquetes si es posible, ya que te ayudará a mantenerte actualizado con las funciones y correcciones de errores más recientes del complemento.

Con este método, aún deberás realizar los pasos de inicialización o registro que se indican en el archivo README del complemento.