Blockly APIs verwenden

Einführung

Auf dieser Seite werden Best Practices für das Aufrufen von Funktionen und den Zugriff auf Haupteigenschaften von Blockly. Diese Prinzipien gelten für die Erstellung von Plug-ins für Blockly oder die Integration von Blockly in eine eigenständige Anwendung.

Abgeleitete Klassen erstellen und erweitern

Blockly bietet mehrere Paradigmen zum Hinzufügen von Funktionen, darunter:

  • Abgeleitete Klassen (z.B. Erstellen eines neuen Renderers)
  • Mixins (z.B. eine Block-Erweiterung oder einen Mutator hinzufügen)
  • Blockdefinitionen (z.B. Definitionen von Prozedurblocks)

Im Rahmen dieses Dokuments entsprechen alle drei Fälle abgeleiteten Klassen an.

Abgeleitete Klassen einfügen

Bestimmte Klassen können mithilfe der Methode Blockly.inject ersetzt werden. Diese Unterklassen müssen entweder die Basisklasse erweitern oder ihre entsprechenden .

Sie können Ihre Unterklasse an die Injection-Methode übergeben.

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

Alternativ können Sie Ihren Kurs mit Blockly.registry anmelden und die Registry-Namen, um die Klasse einzufügen. Dies ist nützlich, wenn du deine Injektion als reines JSON-Format.

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}

Die folgenden Klassen können ersetzt werden:

Name der Registrierung Schnittstelle/Basisklasse
blockDragger Blockly.IBlockDragger
connectionChecker Blockly.IConnectionChecker
connectionPreviewer Blockly.IConnectionPreviewer
flyoutsVerticalToolbox Blockly.IFlyout
flyoutsHorizontalToolbox Blockly.IFlyout
metricsManager Blockly.IMetricsManager
renderer Blockly.blockRendering.Renderer
toolbox Blockly.IToolbox

Weitere Informationen zur Verwendung von Schnittstellen finden Sie im Abschnitt zu Schnittstellen. der Dokumentation.

Sichtbarkeit

Wir verwenden TypeScript-Zugriffsmodifikatoren. um die Sichtbarkeit in der Hauptbibliothek als public, private oder protected zu kennzeichnen. Einige Eigenschaften sind möglicherweise mit @internal in ihren TsDoc-Kommentare.

Alle Properties public und protected sind dokumentiert in der References (Referenzen) der Blockly-Website. Sie können auch überprüfen Sie die Sichtbarkeit, indem Sie den Code lesen.

Öffentlich

Alle mit public gekennzeichneten Elemente sind Teil unserer öffentlichen API. Jedes Attribut in einem Modul die keinen Sichtbarkeitsmodifikator hat, wird als öffentlich betrachtet.

Wir sind bestrebt, unsere öffentliche API nicht häufig oder ohne guten Grund zu ändern. Warnung. Die Ausnahme: Wir machen eine neue API in einem Release öffentlich und in der nächsten Version als Reaktion auf erstes Feedback ändern. Danach können Sie eine öffentliche Funktion oder ein stabiles Eigentum.

Öffentliche Funktionen können von überall aus aufgerufen und in abgeleiteten Klassen wie folgt überschrieben werden: solange sich die Signatur nicht ändert.

geschützt

Auf geschützte Funktionen und Attribute kann nur die definierende Klasse oder eine abgeleitete Klasse.

Abgeleitete Klassen können geschützte Funktionen und Attribute überschreiben, Typsignaturen ändern.

Beispielsweise kann ein benutzerdefinierter Renderer, der die Basis-Renderer-Klasse erweitert, auf ihre geschützten Eigenschaften.

In jedem Fall sollten Sie sicherstellen, dass Sie verstehen, wie die Funktion oder Eigenschaft im restlichen Code verwendet wird.

privat

Auf diese kann nur über Code zugegriffen werden, der sich in derselben Datei wie die Definition befindet. Direkt der Zugriff auf diese Properties zu undefiniertem Verhalten führen kann.

Abgeleitete Klassen dürfen private Funktionen und Attribute nicht überschreiben.

Private Properties können ohne Vorankündigung geändert werden, da sie als Teil der öffentlichen API von Blockly angesehen.

Einige Funktionen in Blockly haben keine Sichtbarkeitshinweise, da sie nicht aus ihrem Modul exportiert. Diese Funktionen sind im Wesentlichen lokale Variablen, und kann nicht außerhalb des zugehörigen Moduls verwendet werden. Sie sollten als Privatgrundstücken gleichwertig sind.

intern

Interne Funktionen und Attribute sollen innerhalb der zentralen in der Bibliothek, aber nicht extern. Sie sind in der TsDoc-Datei @internal angegeben. .

Interne Properties können ohne Vorankündigung geändert werden, da sie als Teil der öffentlichen API von Blockly angesehen.

Auf interne Attribute kann von überall innerhalb von Core zugegriffen werden und sie können in erstellt, solange sich die Signatur nicht ändert. Sie dürfen nicht auf die von außerhalb der Kernbibliothek zugegriffen wird.

Verworfen

Elemente, die mit @deprecated gekennzeichnet sind, sollten nicht verwendet werden. Zu den meisten Einstellungen gehören Anweisungen zum bevorzugten Code, entweder in einer Konsolenwarnung oder in TSDoc.

Wo möglich, wird bei veralteten Funktionen eine Warnung protokolliert, die den beabsichtigten Löschdatum und eine Empfehlung für eine Ersatzfunktion, die aufgerufen werden soll.

Häufig gestellte Fragen

Was kann ich tun, wenn die Funktion, die ich verwenden möchte, nicht öffentlich ist?

Reichen Sie eine Funktionsanfrage ein. auf Blockly. Fügen Sie eine Beschreibung Ihres Anwendungsfalls und eine Beschreibung hinzu, die wir veröffentlichen sollen.

Wir werden die Funktion verwenden, um zu besprechen, ob wir sie veröffentlichen oder ob es andere Möglichkeiten gibt, diese Informationen zu erhalten.

Wenn wir sie veröffentlichen, machen Sie oder das Blockly-Team die Diese Änderung wird in der nächsten Blockly-Version veröffentlicht.

Wenn Sie in einem Plug-in ein nicht-öffentliches Mitglied verwenden möchten, sollten Sie Ihre Plug-in als Beta-Version herunterladen und die Informationen in Ihr README einfügen.

Was ist mit Monkey Patching?

Lesen Sie mehr über Monkey Patching.

MonkeyPatching ist unsicher, da Patches ohne vorherige Ankündigung nicht mehr funktionieren können, der Blockly API zu nutzen. Das Patchen in einem Plug-in besonders gefährlich, da Ihr Code möglicherweise schlecht mit anderen Plug-in, das denselben Code patcht. Aus diesem Grund ist von Monkey Patching in Anwendungen und Plug-ins von Drittanbietern abraten und in eigenen Plug-ins nicht akzeptiert.

Kann ich öffentliche Funktionen überschreiben?

Beim Erstellen von abgeleiteten Klassen: ja. Nein, das ist Monkey Patching.

Kann ich geschützte Funktionen überschreiben?

Beim Erstellen von abgeleiteten Klassen: ja. Nein, das ist Monkey Patching.

Kann ich interne oder private Funktionen überschreiben?

Nein, das ist Monkey Patching.

Wann kann ich direkt auf Properties zugreifen? Wann sollte ich einen Getter oder einen Setter verwenden?

Wenn wir einen Getter oder Setter veröffentlichen, verwende diese statt direkt auf die Property zugreifen. Verwenden Sie auf jeden Fall Getter, wenn die Unterkunft nicht öffentlich ist. und Setter.

Was passiert, wenn eine Eigenschaft keine Anmerkung hat?

Standardmäßig ist dies öffentlich. Bitte setzen Sie sich mit uns in Verbindung, falls wir eine ein Getter/Setter-Paar für Sie einzurichten.

Was ist, wenn eine Funktion keine Annotation hat?

Sie ist standardmäßig öffentlich.

Was mache ich, wenn ich immer noch nicht sicher bin?

Frage im Forum stellen Wir melden uns dann normalerweise innerhalb eines Arbeitstags bei Ihnen.