Auf dieser Seite werden Best Practices zum Aufrufen von Funktionen und zum Zugriff auf Eigenschaften in Blockly beschrieben. Diese Prinzipien gelten für das Erstellen von Plug-ins für Blockly und für die Einbindung von Blockly in eine eigenständige Anwendung.
Sichtbarkeit
Wir verwenden TypeScript-Zugriffsmodifikatoren, um die Sichtbarkeit in der Kernbibliothek als public, private oder protected zu kennzeichnen.
Einige Properties sind möglicherweise in den TsDoc-Kommentaren mit @internal gekennzeichnet.
Alle public- und protected-Properties sind auf der Blockly-Website im Abschnitt References (Referenzen) dokumentiert. Sie können die Sichtbarkeit auch anhand des Codes prüfen.
Öffentlich
Alle mit public gekennzeichneten Elemente sind Teil unserer öffentlichen API. Alle Properties in einem Modul, die keinen Sichtbarkeitsmodifikatoren haben, gelten als öffentlich.
Wir versuchen, unsere öffentliche API nicht häufig oder ohne triftigen Grund und Warnung zu ändern. Ausnahme: Wir können eine neue API in einer Version veröffentlichen und sie in der nächsten Version aufgrund von frühem Feedback ändern. Danach können Sie eine öffentliche Funktion oder Property als stabil betrachten.
Öffentliche Funktionen können von überall aufgerufen und in Unterklassen überschrieben werden, solange sich die Signatur nicht ändert.
geschützt
Auf geschützte Funktionen und Eigenschaften kann nur über die definierende Klasse oder eine Unterklasse zugegriffen werden.
Unterklassen dürfen geschützte Funktionen und Eigenschaften überschreiben, ohne die Typsignaturen zu ändern.
Beispielsweise kann ein benutzerdefinierter Renderer, der die Basis-Renderer-Klasse erweitert, auf deren geschützte Eigenschaften zugreifen.
In jedem Fall sollten Sie wissen, wie die Funktion oder das Attribut im Rest des Codes verwendet wird.
privat
Auf diese kann nur über Code in derselben Datei wie die Definition zugegriffen werden. Der direkte Zugriff auf diese Properties kann zu undefiniertem Verhalten führen.
In Unterklassen dürfen keine privaten Funktionen und Eigenschaften überschrieben werden.
Private Properties können ohne vorherige Ankündigung geändert werden, da sie nicht Teil der öffentlichen API von Blockly sind.
Einige Funktionen in Blockly haben keine Sichtbarkeitsanmerkungen, da sie nicht aus ihrem Modul exportiert werden. Diese Funktionen sind im Grunde lokale Variablen und können nicht außerhalb des definierenden Moduls verwendet werden. Sie sollten als Privatunterkünfte betrachtet werden.
intern
Interne Funktionen und Eigenschaften sind für die Verwendung innerhalb der Kernbibliothek vorgesehen, nicht extern. Sie sind mit der TsDoc-@internal-Anmerkung gekennzeichnet.
Interne Eigenschaften können ohne vorherige Ankündigung geändert werden, da sie nicht zur öffentlichen API von Blockly gehören.
Auf interne Properties kann von überall im Core zugegriffen und sie in Unterklassen im Core überschrieben werden, solange sich die Signatur nicht ändert. Der Zugriff darauf darf nicht von außerhalb der Kernbibliothek erfolgen.
Verworfen
Elemente, die mit @deprecated gekennzeichnet sind, sollten nicht verwendet werden. Die meisten Einstellungsankündigungen enthalten eine Anleitung zum bevorzugten Code, entweder in einer Konsolenwarnung oder in einem TSDoc.
Wenn möglich, wird für eingestellte Funktionen eine Warnung protokolliert, die das geplante Löschdatum und eine Empfehlung für eine aufzurufende Ersatzfunktion enthält.
Häufig gestellte Fragen
Im Folgenden finden Sie einige häufig gestellte Fragen, die dem Blockly-Team begegnet sind.
Was ist, wenn die Funktion, die ich verwenden möchte, nicht öffentlich ist?
Stellen Sie eine Funktionsanfrage für Blockly Core. Fügen Sie eine Beschreibung Ihres Anwendungsfalls und eine Erklärung dazu hinzu, was wir veröffentlichen sollen.
Wir nutzen die Funktion, um zu erfragen, ob die Informationen veröffentlicht werden sollen oder ob es andere Möglichkeiten gibt, an dieselben Informationen zu gelangen.
Wenn wir uns dafür entscheiden, sie öffentlich zu machen, nehmen entweder Sie oder das Blockly-Team die entsprechenden Änderungen vor. Sie werden dann im nächsten Blockly-Release veröffentlicht.
Wenn Sie ein nicht öffentliches Mitglied in einem Plug-in verwenden, sollten Sie Ihr Plug-in als Beta kennzeichnen und die Informationen in Ihre README aufnehmen.
Was ist mit Monkeypatching?
Weitere Informationen zu Monkeypatching
Monkeypatching ist unsicher, da Patches ohne vorherige Ankündigung aufgrund der Verwendung nicht öffentlicher Teile der Blockly API nicht mehr funktionieren können. Das Patchen in einem Plug-in ist besonders gefährlich, da Ihr Code möglicherweise nicht gut mit anderen Plug-ins interagiert, die denselben Code mit Monkeypatching ändern. Aus diesem Grund empfehlen wir dringend, Monkeypatching in Anwendungen und Drittanbieter-Plug-ins zu vermeiden. In eigenen Plug-ins ist es nicht zulässig.
Kann ich öffentliche Funktionen überschreiben?
Bei der Ableitung einer Klasse: ja. Andernfalls: Nein, das ist Monkeypatching.
Kann ich geschützte Funktionen überschreiben?
Bei der Ableitung einer Klasse: ja. Andernfalls: Nein, das ist Monkeypatching.
Kann ich interne oder private Funktionen überschreiben?
Nein, das ist Monkeypatching.
Wann kann ich direkt auf Unterkünfte zugreifen? Wann sollte ich einen Getter oder einen Setter verwenden?
Wenn wir einen Getter oder einen Setter veröffentlichen, verwende diese, anstatt direkt auf die Property zuzugreifen. Wenn die Eigenschaft nicht öffentlich ist, sollten Sie unbedingt Getter und Setter verwenden.
Was ist, wenn eine Property keine Anmerkung hat?
Standardmäßig ist sie öffentlich. Wenn Sie möchten, dass wir ein Get-/Set-Paar für Sie einrichten, schreiben Sie uns bitte eine Nachricht.
Was ist, wenn eine Funktion keine Anmerkung hat?
Sie ist standardmäßig öffentlich.
Was ist, wenn ich mir immer noch nicht sicher bin?
Stelle deine Frage im Forum und wir melden uns innerhalb weniger Tage bei dir.