Publica bibliotecas de bloques

Los complementos que proporcionan bibliotecas de definiciones de bloques son una excelente manera de compartir estos elementos. tus bloques reutilizables con la comunidad de Blockly. Para que tu biblioteca de bloques sea lo más versátil y útil posible, desarrollamos estos lineamientos.

Lineamientos

• Haz que sea fácil para los usuarios instalar todos tus bloques posible para que los usuarios instalen solo algunos bloques o fragmentos de bloques que elijan.
  • Facilita la instalación de todo: Para ello, proporciona una función que instale cada elemento que requiera una sola definición de bloque (como modificadores, extensiones, mixins, campos, etcétera). También puedes proporcionar una función que instale todos los bloques que ofrece tu complemento a la vez.
  • Permite elegir partes específicas: Debes exportar todas las partes de una definición de bloque por separado, de modo que un usuario pueda importar solo las partes que necesita para crear su propio bloque personalizado similar.
• Evita usar efectos secundarios en tu complemento.
  • Los bloques, campos, extensiones y otras piezas no deben instalarse como efecto secundario de cargar el complemento. Los usuarios deben mantener el control sobre qué se instala y cuándo. Esto permite a los usuarios importar las piezas que necesitan sin preocuparse de que se instalen piezas que no necesitan.

• Usa el registro de campos JSON en lugar de crear instancias de campos nuevos directamente.

  • No recomendado. Crea una instancia de un campo nuevo directamente:

      const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(new Blockly.FieldNumber(123), 'NAME');
        }
      }
    

  • Recomendado: Registro de campos JSON:

      export const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(Blockly.fieldRegistry.fromJson({
                  name: 'field_number',
                  value: 123,
                }), 'NAME');
        }
      }
    

  • El uso del registro de campos permite que un usuario reemplace la implementación del campo que se usa en tu bloque sin tener que cambiar la definición del bloque.

• No hagas suposiciones sobre lo que el usuario ya instaló.

  • Si tu complemento requiere un campo personalizado o otro complemento, regístralo en la función install que proporcionaste.
  • Pronto, Blockly proporcionará herramientas que te permitirán registrar elementos ya registrados sin errores. Hasta entonces, te recomendamos que revises lo que ya se registró antes de registrar una extensión, un mutador, un mixin o un campo.
  • Sé claro sobre los requisitos previos o las dependencias que requieren tu complemento o las definiciones de bloque.

• Considera proporcionar funciones generadoras para cada uno de los bloques que proporciones.

  • Proporcionar funciones de generador que funcionen de inmediato facilita que los usuarios usen tus bloques sin tener que comprender su estructura y diseño. Si deben escribir su propio generador funciones, esto puede llevar a que cada usuario realice un trabajo redundante.
  • JavaScript es el lenguaje que más se usa en Blockly, así que si solo elija un idioma para proporcionar, recomendamos JavaScript, a menos que los bloqueos se compilan para un lenguaje específico, como la implementación de una biblioteca de Python.
  • Considera publicar problemas de "se necesita ayuda" para los idiomas para los que no puedes implementar funciones de generador y acepta solicitudes de extracción para estos si un usuario las contribuye.

  • Si proporcionas una función de instalación para tu bloque, puedes aceptar un el parámetro opcional generators. Si un usuario pasa una instancia de generador puedes instalar automáticamente el generador de código de bloque función y realizar tareas relacionadas, como agregar palabras reservadas:

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.common.defineBlocks({my_custom_block: myCustomBlock});
        if (generators.javascript) {
          generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
          generators.javascript.addReservedWords('specialReservedWord');
        }
      }
    
      // How a user may install your block
      import {javascriptGenerator} from 'blockly/javascript';
      import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
      // installs the block definition and the javascript block-code generator
      installMyCustomBlock({javascript: javascriptGenerator});
    

Comentarios

Si tienes preguntas sobre cómo seguir mejor estos lineamientos en el complemento, cuéntanos en el foro. Nos encantaría ver tus bibliotecas de bloques y brindarte comentarios sobre ellas.

Ten en cuenta que no todos los complementos propios que proporcionan definiciones de bloqueo actualmente siguen estos lineamientos, pero los nuevos complementos sí lo harán, y planeamos migrar los existentes o complementos.