In diesem Dokument wird beschrieben, wie Sie ein neues Plug-in erstellen. Der beschriebene Prozess bezieht sich auf das Erstellen von Erstanbieter-Plug-ins, kann aber auch als Richtlinie für das Erstellen von Drittanbieter-Plug-ins verwendet werden.
Eine Übersicht über Plug-ins finden Sie unter Plug-ins.
Eine kurze Einführung zum Erstellen eines Plug‑ins finden Sie in unserem Vortrag zum Erstellen eines Plug‑ins (2021).
Selbst erhobene Daten im Vergleich zu Daten von Drittanbietern
Die Zielgruppe für ein Plug-in ist ein Entwickler, der das Plug-in über npm findet und verwendet.
Erstanbieter-Plug-ins werden vom Blockly-Team unterstützt und unter dem Bereich @blockly
auf npm veröffentlicht. Sie sind für eine Vielzahl von Blockly-Anwendungen konzipiert und sind stabil und einfach zu verwenden. Sie werden in blockly-samples gespeichert. Ein Feld zum Einstellen der Motordrehzahl könnte in vielen Robotikprojekten verwendet werden und ist ein guter Kandidat für ein eigenes Plug-in.
Plug-ins von Drittanbietern werden unabhängig verwaltet und veröffentlicht. Sie sind möglicherweise komplexer, experimenteller oder auf einen engeren Bereich von Blockly-Anwendungen ausgerichtet. Ein Feld zum Bearbeiten eines bestimmten Objekts, das durch Ihr Datenbankschema definiert wird, ist besser als Drittanbieter-Plug-in geeignet.
Kriterien für selbst erhobene Daten
Erstanbieter-Plug-ins müssen die folgenden Anforderungen erfüllen:
- Auf allen wichtigen Plattformen funktionieren, sofern das Blockly-Team keine Ausnahme gewährt hat.
- Chrome, Firefox, Safari, Edge
- Sie haben einen Autor, der bereit ist, sich im ersten Jahr um Fehler zu kümmern.
- Blockly darf nicht manipuliert werden.
- Eine klar definierte und dokumentierte API.
- Rufen Sie keine privaten oder Paketfunktionen aus Blockly Core auf, es sei denn, das Blockly-Team hat Ihnen eine Ausnahme gewährt.
- Das Überschreiben von Paketfunktionen in einer von Ihnen definierten Unterklasse ist zulässig.
- Wenn Sie eine Ausnahme beantragen möchten, stellen Sie uns eine Frage im Issue-Tracker von blockly-samples.
- Tests
Vorgehensweise
Plugins durchlaufen vier Phasen: Vorschlag, Diskussion, Implementierung und Veröffentlichung.
Vorschlag
Ein Plug-in beginnt als Vorschlag. Sie können ein Plugin vorschlagen, indem Sie ein neues Problem mit der Vorlage Feature Request (Funktionsanfrage) erstellen. Weitere Informationen zum Schreiben von Funktionsanfragen
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 Core hinzugefügt oder geändert werden müssen, um das Plug-in zu unterstützen.
- Screenshots, GIFs oder Mock-ups, wenn das Plug-in UI-Funktionen enthält.
- Eine Erklärung, warum es sich um ein selbst entwickeltes Plug-in und nicht um ein Drittanbieter-Plug-in handeln sollte.
Das Blockly-Team prüft eingehende Vorschläge und schließt das Problem entweder oder stimmt zu, dass es sich um ein gutes Erstanbieter-Plug-in handeln würde.
Diskussion
Als Nächstes geht ein Plugin in die Diskussionsphase über. Diese Phase umfasst:
- Klärung der gewünschten Funktion.
- Die API des Plug‑ins wurde näher erläutert.
- Implementierung planen
- Tests planen.
- Diskussion von API-Änderungen in Blockly Core.
- Große Plugins in Implementierungsschritte aufteilen.
- Die Benennung von Plugins basiert auf unseren Namenskonventionen.
- Bestätigung, dass alle Erstanbieterkriterien erfüllt werden.
Die Diskussion findet in der Regel im GitHub-Issue statt. Je kleiner der Umfang des Plugins ist, desto schneller kann die Diskussionsphase abgeschlossen werden. Größere Plugins 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! Du hast etwas gefunden, das Menschen interessiert.
Ziel ist es, dass am Ende der Diskussionsphase alle wichtigen Designentscheidungen getroffen wurden und eine klare Liste der Implementierungsschritte vorliegt. 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 unter dem Bereich @blockly
veröffentlicht werden sollte. In diesem Fall erklären wir, warum, und schließen das Problem.
Wenn die Diskussion abgeschlossen ist, vermerkt ein Blockly-Teammitglied, dass die Funktion implementiert werden kann.
Implementierung
Die Implementierung umfasst folgende Schritte:
- Führen Sie
npx @blockly/create-package
aus, um das Plug-in und sein Verzeichnis anhand einer Vorlage einzurichten. Weitere Informationen - Implementierung der Kernlogik für das Plug‑in.
- Bei Bedarf eine Benutzeroberfläche implementieren.
- Plug-in mit Mocha testen
- Dokumentieren Sie das Plug-in, 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 offen für Beiträge ist.
Die Implementierung kann von mehreren Mitwirkenden parallel erfolgen. Sie können ein Plug-in gemeinsam in Ihrem eigenen Fork oder über Pull-Anfragen für dieses Repository implementieren. Wenn Sie an einem Plug-in in diesem Repository mitarbeiten möchten, bitten Sie das Blockly-Team, einen Feature-Branch für Sie zu erstellen.
Plug-ins sollten der Datei gh-pages/index.md
im master
-Branch von blockly-samples hinzugefügt werden. Dadurch werden sie auf unserer Website für Plugins angezeigt. Eigene Plugins sollten auf ihre Testseite verweisen. Auf dieser Seite können auch Drittanbieter-Plug-ins hinzugefügt werden, die auf einen Link nach Wahl des Inhabers verweisen, z. B. auf eine gehostete Demo oder die npm-Seite.
Wird veröffentlicht
Schließlich veröffentlichen. Das Blockly-Team verwendet Lerna, um die Versionsverwaltung 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 schneller veröffentlicht werden soll, gib das bitte in deinem Pull-Request an.
Die Plugins-Website wird auch immer dann aktualisiert, wenn Plugins veröffentlicht werden.
Plugins, die noch nicht für die Veröffentlichung bereit sind, sollten in ihrer package.json
mit private
gekennzeichnet werden. Das kann passieren, wenn ein Plug-in auf einer noch nicht veröffentlichten Änderung in Core Blockly basiert. Core Blockly wird in der letzten Woche jedes Quartals (alle drei Monate) veröffentlicht.