Blockbibliotheken veröffentlichen

Plugins, die Bibliotheken mit Blockdefinitionen bereitstellen, sind eine gute Möglichkeit, Ihre wiederverwendbaren Blöcke mit der Blockly-Community zu teilen. Damit Ihre Blockbibliothek möglichst vielseitig und nützlich ist, haben wir diese Richtlinien entwickelt.

Richtlinien

Ermöglichen Sie Nutzern, alle Blöcke zu installieren, und machen Sie es ihnen möglich, nur bestimmte Blöcke oder Teile von Blöcken zu installieren.
- Erleichtern Sie die Installation: Dazu können Sie eine Funktion bereitstellen, die alle Teile installiert, die für eine einzelne Blockdefinition erforderlich sind (z. B. Mutatatoren, Erweiterungen, Mixins, Felder usw.). Sie können auch eine Funktion bereitstellen, mit der alle Blöcke, die von Ihrem Plug-in angeboten werden, gleichzeitig installiert werden.
- Es muss möglich sein, bestimmte Teile auszuwählen: Sie sollten alle Teile einer Blockdefinition separat exportieren, damit Nutzer nur die Teile importieren können, die sie benötigen, um einen eigenen ähnlichen benutzerdefinierten Block zu erstellen.
Verwenden Sie in Ihrem Plug-in keine Nebeneffekte.
- Blöcke, Felder, Erweiterungen und andere Komponenten sollten beim Laden des Plug-ins nicht installiert werden. Nutzer sollten die Kontrolle darüber behalten, was und wann installiert wird. So können Nutzer die benötigten Teile importieren, ohne sich Gedanken darüber machen zu müssen, dass nicht benötigte Teile installiert werden.

Verwenden Sie die JSON-Feldregistrierung, anstatt neue Felder direkt zu instanziieren.

Nicht empfohlen: Direktes Instanziieren eines neuen Felds:

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

Empfohlen – JSON-Feld-Registry:

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

Mit der Feldregistrierung kann ein Nutzer die Implementierung des Felds, das in Ihrem Block verwendet wird, leichter ersetzen, ohne die Blockdefinition ändern zu müssen.

Machen Sie keine Annahmen darüber, was der Nutzer bereits installiert hat.
- Wenn für Ihr Plug-in ein benutzerdefiniertes Feld oder ein anderes Plug-in erforderlich ist, registrieren Sie diese Felder selbst in der von Ihnen bereitgestellten install-Funktion.
- Bald wird Blockly Tools bereitstellen, mit denen Sie bereits registrierte Artikel fehlerfrei registrieren können. Bis dahin sollten Sie überprüfen, was bereits registriert wurde, bevor Sie selbst eine Erweiterung, einen Mutator, ein Mixin oder ein Feld registrieren.
- Machen Sie alle Voraussetzungen oder Abhängigkeiten deutlich, die für Ihre Plug-in- oder Blockdefinitionen erforderlich sind.
Sie sollten für jeden Block, den Sie bereitstellen, Generatorfunktionen angeben.
- Wenn Sie Generatorfunktionen bereitstellen, die sofort einsatzbereit sind, können Nutzer Ihre Blöcke leichter verwenden, ohne ihre Struktur und ihr Design verstehen zu müssen. Wenn sie ihre eigenen Generatorfunktionen schreiben müssen, kann dies zu redundanter Arbeit für jeden Nutzer führen.
- JavaScript ist die am häufigsten verwendete Sprache in Blockly. Wenn Sie nur eine Sprache auswählen, empfehlen wir JavaScript, es sei denn, Ihre Blöcke sind für eine bestimmte Sprache entwickelt, z. B. für die Implementierung einer Python-Bibliothek.
- Erwägen Sie, Hilfeprobleme für Sprachen zu posten, für die Sie keine Generatorfunktionen implementieren können, und akzeptieren Sie Pull-Anfragen dafür, wenn ein Nutzer sie beisteuert.
- Wenn Sie eine Installationsfunktion für Ihren Block angeben, können Sie einen optionalen Parameter generators akzeptieren. Wenn ein Nutzer eine von Ihnen unterstützte Generatorinstanz übergibt, können Sie die Block-Code-Generatorfunktion automatisch installieren und damit verbundene Aufgaben ausführen, z. B. reservierte Wörter hinzufügen:
```
  // 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});
```

Feedback

Wenn du Fragen dazu hast, wie du diese Richtlinien in deinem Plug-in am besten umsetzen kannst, kannst du dich jederzeit im Forum an uns wenden. Wir würden uns sehr über Ihre Blockbibliotheken freuen und Ihnen Feedback dazu geben.

Hinweis: Nicht alle eigenen Plug-ins mit Blockdefinitionen entsprechen derzeit diesen Richtlinien. Für neue Plug-ins ist dies jedoch erforderlich und wir planen, vorhandene Plug-ins zu migrieren.