Cómo publicar bibliotecas de bloques

Los complementos que proporcionan bibliotecas de definiciones de bloques son una excelente manera de compartir 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 y que sea posible que instalen solo ciertos bloques o partes 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, los campos, las extensiones y otros elementos no deben instalarse como efecto secundario de la carga del complemento. Los usuarios deben controlar qué cosas se instalan y cuándo. Esto permite a los usuarios importar las piezas que necesitan sin preocuparse de que se instalen las que no.

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

  • No se recomienda crear 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 el complemento requiere un campo personalizado o algún otro complemento, registra esos campos tú mismo en la función install proporcionada.
  • Pronto, Blockly proporcionará herramientas que te permitirán registrar elementos ya registrados sin errores. Hasta entonces, te recomendamos que compruebes 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 de generador 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 tienen que escribir sus propias funciones de generador, esto puede provocar que cada usuario realice un trabajo redundante.
  • JavaScript es el lenguaje más usado en Blockly, por lo que, si solo eliges un lenguaje para proporcionar, te recomendamos JavaScript, a menos que tus bloques se compilen para un lenguaje específico, como la implementación de una biblioteca de Python.
  • Considera publicar problemas de "ayuda requerida" para los idiomas para los que no puedes implementar funciones de generador y acepta solicitudes de extracción para estos si un usuario las agrega.

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

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.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 estos lineamientos en tu complemento, comunícate con nosotros en el foro. Nos encantaría ver tus bibliotecas de bloques y brindarte comentarios sobre ellas.

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