Blockly APIs verwenden

Einleitung

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

Abgeleitete Klassen erstellen und erweitern

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

  • Abgeleitete Klassen (z.B. zum Erstellen eines neuen Renderers)
  • Mixins (z.B. Hinzufügen einer Blockerweiterung oder eines Mutators)
  • Blockdefinitionen (z.B. Definitionen von Prozedurblöcken)

Für die Zwecke dieses Dokuments entsprechen alle drei Fälle der Ableitung von abgeleiteten Klassen.

Unterklassen einschleusen

Wir unterstützen das Ersetzen bestimmter Klassen durch die Methode Blockly.inject. Diese abgeleiteten Klassen müssen entweder die Basisklasse erweitern oder die entsprechende Schnittstelle implementieren.

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

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

Alternativ können Sie Ihre Klasse mit Blockly.registry registrieren und den Registry-Namen verwenden, um die Klasse einzuschleusen. Dies ist nützlich, wenn Sie die Injection-Optionen als reines JSON-Format speichern.

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 in der Dokumentation im Abschnitt zu Schnittstellen.

Sichtbarkeit

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

Alle public- und protected-Properties sind im Abschnitt Referenzen der Blockly-Website dokumentiert. Sie können die Sichtbarkeit auch prüfen, indem Sie den Code lesen.

Öffentlich

Alles, was mit public gekennzeichnet ist, ist Teil unserer öffentlichen API. Alle Eigenschaften in einem Modul, die keinen Sichtbarkeitsmodifikator haben, gelten als öffentlich.

Wir versuchen, Änderungen an unserer öffentlichen API nicht häufig oder ohne guten Grund und mit einer Warnung vorzunehmen. Ausnahme: Wir können eine neue API in einem Release veröffentlichen und als Reaktion auf frühzeitiges Feedback im nächsten Release ändern. Danach können Sie eine öffentliche Funktion oder eine stabile Eigenschaft betrachten.

Öffentliche Funktionen können von überall aus aufgerufen und in Unterklassen überschrieben werden, solange sich die Signatur nicht ändert.

geschützt

Auf geschützte Funktionen und Attribute darf nur von der definierenden Klasse oder einer Unterklasse zugegriffen werden.

Abgeleitete Klassen dürfen geschützte Funktionen und Attribute überschreiben, ohne Typsignaturen zu ändern.

Beispielsweise kann ein benutzerdefinierter Renderer, der die Basis-Rendererklasse erweitert, auf seine geschützten Eigenschaften zugreifen.

Sie sollten in jedem Fall wissen, wie die Funktion oder Eigenschaft im restlichen Code verwendet wird.

private

Auf diese kann nur über Code in derselben Datei wie die Definition zugegriffen werden. Der direkte Zugriff auf diese Attribute kann zu undefiniertem Verhalten führen.

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

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

Einige Funktionen in Blockly haben keine Sichtbarkeitsanmerkungen, da sie nicht aus ihrem Modul exportiert werden. Diese Funktionen sind im Wesentlichen lokale Variablen und können nicht außerhalb des definierenden Moduls verwendet werden. Sie sollten als äquivalent zu Privatgrundstücken angesehen werden.

intern

Interne Funktionen und Attribute sind für die Verwendung in der Kernbibliothek vorgesehen, nicht jedoch extern. Sie sind mit der TsDoc-Anmerkung @internal gekennzeichnet.

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

Auf interne Attribute kann von überall aus innerhalb des Core zugegriffen und sie in untergeordneten Klassen im Core überschrieben werden, solange sich die Signatur nicht ändert. Sie dürfen nicht von außerhalb der Kernbibliothek aufgerufen werden.

Verworfen

Mit @deprecated gekennzeichnete Elemente sollten nicht verwendet werden. Die meisten Einstellungen enthalten Anweisungen zum bevorzugten Code, entweder in einer Konsolenwarnung oder in einem TSDoc.

Nach Möglichkeit wird für verworfene Funktionen eine Warnung protokolliert, die das vorgesehene Löschdatum und eine Empfehlung für den Aufruf einer Ersatzfunktion enthält.

FAQs

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

Reichen Sie eine Funktionsanfrage für Core Blockly ein. Beschreiben Sie Ihren Anwendungsfall und geben Sie an, was wir veröffentlichen sollen.

Wir verwenden die Funktion, um zu erörtern, ob wir sie veröffentlichen oder ob es andere Möglichkeiten gibt, dieselben Informationen zu erhalten.

Wenn wir beschließen, sie zu veröffentlichen, nehmen entweder Sie oder das Blockly-Team die entsprechende Änderung vor, und sie wird im nächsten Blockly-Release veröffentlicht.

Wenn Sie in einem Plug-in ein nicht öffentliches Mitglied verwenden, sollten Sie das Plug-in als Beta markieren und die entsprechenden Informationen in Ihr README aufnehmen.

Wie sieht es mit Monkey Patching aus?

Weitere Informationen zu Monkeypatching

Monkeypatching ist unsicher, da Patches aufgrund der Verwendung nicht öffentlicher Teile der Blockly API ohne Vorankündigung nicht mehr funktionieren können. Das Patchen in einem Plug-in ist besonders gefährlich, da Ihr Code unter Umständen mit anderen Plug-ins interagieren kann, die denselben Code patchen. Aus diesem Grund empfehlen wir Monkeypatching dringend in Anwendungen und Plug-ins von Drittanbietern und auch in eigenen Plug-ins nicht.

Kann ich öffentliche Funktionen überschreiben?

Bei Unterklassen: Ja. Andernfalls: Nein, das ist Monkey Patching.

Kann ich geschützte Funktionen überschreiben?

Bei Unterklassen: Ja. Andernfalls: 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 Setter verwenden?

Wenn wir einen Getter oder Setter veröffentlichen, verwenden Sie bitte diesen, anstatt direkt auf die Property zuzugreifen. Wenn das Attribut nicht öffentlich ist, sollten Sie auf jeden Fall Getter und Setter verwenden.

Was ist, wenn eine Unterkunft keine Anmerkung hat?

Standardmäßig ist es öffentlich, aber lassen Sie uns bitte eine Zeile, falls wir ein Getter/Setter-Paar für Sie verwenden möchten.

Was passiert, wenn eine Funktion keine Annotation hat?

Standardmäßig ist es öffentlich.

Was kann ich tun, wenn ich mir immer noch nicht sicher bin?

Sie können eine Frage im Forum stellen. Wir melden uns dann in der Regel innerhalb eines Arbeitstags bei Ihnen.