In diesem Dokument wird beschrieben, wie Sie ein neues Plug-in erstellen. Der beschriebene Prozess bezieht sich zwar auf das Erstellen von eigenen Plugins, kann aber auch als Leitfaden für das Erstellen von Drittanbieter-Plugins verwendet werden.
Eine Übersicht über Plug-ins finden Sie unter Plug-ins.
Eine kurze Einführung in die Erstellung eines Plug-ins findest du in unserem Talk zum Erstellen eines Plug-ins (2021).
Zielgruppen mit selbst erhobenen Daten und Drittanbieter-Zielgruppen
Der Zielnutzer eines Plug-ins ist ein Entwickler, der das Plug-in über npm findet und verwendet.
Eigene Plug-ins werden vom Blockly-Team unterstützt und unter @blockly auf npm veröffentlicht. Sie sind für die Verwendung in einer Vielzahl von Blockly-Anwendungen konzipiert und stabil und einfach zu verwenden. Sie werden in blockly-samples gespeichert. Ein Feld zum Einstellen der Motorgeschwindigkeit könnte in vielen Roboterprojekten verwendet werden und ist ein guter Kandidat für ein eigenes Plug-in.
Drittanbieter-Plug-ins werden unabhängig verwaltet und veröffentlicht. Sie können komplexer, experimenteller oder auf eine kleinere Bandbreite von Blockly-Anwendungen ausgerichtet sein. Ein Feld zum Bearbeiten eines bestimmten Objekts, das durch Ihr Datenbankschema definiert ist, eignet sich besser als Drittanbieter-Plug-in.
Selbst erhobene Daten
Eigene Plug-ins müssen diese Anforderungen erfüllen:
- Sie funktionieren auf allen gängigen Plattformen, sofern das Blockly-Team keine Ausnahmeregelung gewährt.
- Chrome, Firefox, Safari, Edge
- Sie haben einen Entwickler, der bereit ist, im ersten Jahr Fehler zu beheben.
- Blockly darf nicht gepatcht werden.
- Sie haben eine klar definierte und dokumentierte API.
- Rufen Sie keine privaten oder Paketfunktionen aus dem Blockly-Kern auf, es sei denn, das Blockly-Team hat eine Ausnahme gewährt.
- Es ist zulässig, Paketfunktionen in einer von Ihnen definierten Unterklasse zu überschreiben.
- Wenn Sie eine Ausnahme benötigen, stellen Sie uns eine Anfrage in einem Issue auf blockly-samples.
- Tests durchführen
Vorgehensweise
Plugins durchlaufen vier Phasen: Vorschlag, Diskussion, Implementierung und Veröffentlichung.
Vorschlag
Ein Plug-in beginnt als Vorschlag. Wenn du ein Plug-in vorschlagen möchtest, erstelle ein neues Problem mit der Vorlage Feature Request.
Informationen zum Erstellen einer Funktionanfrage
Zusätzlich zu den grundlegenden Informationen zur Funktionsanfrage sollte ein Plug-in-Vorschlag Folgendes enthalten:
- Die API, die das Plug-in bereitstellen würde.
- APIs, die in Blockly hinzugefügt oder geändert werden müssen, um das Plug-in zu unterstützen.
- Screenshots, GIFs oder Mockups, wenn das Plug-in UI-Funktionen enthält
- Eine Erklärung, warum es sich um ein eigenes Plug-in und nicht um ein Drittanbieter-Plug-in handeln sollte.
Das Blockly-Team prüft die Vorschläge nach und nach und schließt das Problem entweder oder stimmt zu, dass es sich um ein gutes Plug-in von Google handelt.
Diskussion
Als Nächstes geht es in die Diskussionsphase. Diese Phase umfasst:
- Klärung der gewünschten Funktionalität.
- Die API des Plug-ins wurde näher erläutert.
- Implementierung planen
- Tests planen
- Diskussion zu API-Änderungen im Blockly-Kern
- Große Plug-ins in Implementierungsschritte unterteilen
- Die Benennung von Plug-ins muss unseren Namenskonventionen entsprechen.
- Prüfen, ob alle Kriterien für selbst erhobene Daten erfüllt sind.
Diese Diskussion findet in der Regel im GitHub-Problem statt. Je kleiner der Umfang des Plug-ins ist, desto schneller kann die Diskussionsphase sein. Größere Plug-ins können die Aufmerksamkeit der Community auf sich ziehen und zu starken Meinungen über die richtige Lösung führen. Wenn das bei Ihrem Problem der Fall ist, herzlichen Glückwunsch! Sie haben etwas gefunden, das Menschen interessiert.
Ziel ist es, dass am Ende der Diskussionsphase alle wichtigen Designentscheidungen getroffen wurden und es eine klare Liste der Implementierungsschritte gibt. Beides sollte in Kommentaren zum Problem dokumentiert werden.
Während der Diskussion können wir entscheiden, dass ein Plug-in ein Drittanbieter-Plug-in sein sollte und nicht im Rahmen von @blockly veröffentlicht werden darf. In diesem Fall erklären wir Ihnen den Grund und schließen das Problem.
Nach Abschluss der Diskussion gibt ein Mitglied des Blockly-Teams an, dass die Funktion implementiert werden kann.
Implementierung
Zu den Implementierungsschritten gehören:
npx @blockly/create-packageausführen, um das Plug-in und sein Verzeichnis aus einer Vorlage einzurichten Weitere Informationen- Implementieren der Kernlogik für das Plug-in
- Implementieren einer Benutzeroberfläche, falls erforderlich
- Testen des Plug-ins mit Mocha
- Dokumentation des Plug-ins, einschließlich der
README.
Wenn ein vorgeschlagenes Plug-in für die Implementierung genehmigt wurde und Sie daran arbeiten möchten, kommentieren Sie das Problem und fragen Sie, ob es noch für Beiträge offen ist.
Die Implementierung kann von mehreren Mitwirkenden parallel erfolgen. Sie können ein Plug-in gemeinsam in Ihrem eigenen Fork oder über Pull-Anfragen an dieses Repository implementieren. Wenn Sie an einem Plug-in in diesem Repository zusammenarbeiten möchten, bitten Sie das Blockly-Team, einen Feature-Branch für Sie zu erstellen.
Plugins sollten der Datei gh-pages/index.md im master-Zweig von blockly-samples hinzugefügt werden. Sie werden dann auf unserer Website für Plugins angezeigt. Plugins von Erstanbietern sollten auf die Testseite verweisen. Diese Seite kann auch mit Drittanbieter-Plug-ins ergänzt werden, die auf einen Link der Wahl des Eigentümers verweisen, z. B. auf eine gehostete Demo oder die npm-Seite.
Wird veröffentlicht
Zum Schluss folgt die Veröffentlichung. Das Blockly-Team verwendet Lerna, um die Versionierung und Veröffentlichung aller Plug-ins zu verwalten.
Jeden Donnerstag werden alle Plugins veröffentlicht, die sich seit der letzten Veröffentlichung geändert haben. Wenn eine Änderung früher veröffentlicht werden soll, geben Sie dies bitte in Ihrem Pull-Request an.
Die Website „Plugins“ wird auch aktualisiert, wenn Plugins veröffentlicht werden.
Plugins, die noch nicht zur Veröffentlichung bereit sind, sollten in ihrem package.json mit private gekennzeichnet sein. Das kann passieren, wenn ein Plug-in auf einer noch nicht veröffentlichten Änderung im Blockly-Kern basiert. Core Blockly wird in der letzten Woche jedes Quartals (alle drei Monate) veröffentlicht.