Upgrade für ein benutzerdefiniertes Feld durchführen

Im Juli 2019 (Version 2.20190722) wurde eine API für mehr kodifizierte Felder hinzugefügt. Sie soll so abwärtskompatibel wie möglich sein. Wenn Sie also ein benutzerdefiniertes Feld vor Juli 2019 erstellt haben, wird es höchstwahrscheinlich weiterhin funktionieren. Bevor Sie entscheiden, ob Ihr benutzerdefiniertes Feld aktualisiert werden muss, sollten Sie den Abschnitt Gefahrene Bereiche lesen und Ihr Feld gründlich testen.

Da die Felder vor Juli 2019 nicht standardisiert wurden, ist es schwierig, alle Änderungen abzudecken, die ein Entwickler möglicherweise vornehmen muss. In diesem Dokument werden alle wahrscheinlichen Änderungen abgedeckt. Falls dieses Dokument jedoch nicht für Sie von Interesse ist, lesen Sie den Abschnitt Unterstützung beim Upgrade anfordern.

Hinweis: Wenn Sie nur wenige benutzerdefinierte Felder haben, ist es möglicherweise einfacher, sie mit der Anleitung zum Erstellen benutzerdefinierter Felder neu zu schreiben, anstatt zu versuchen, sie einzeln zu aktualisieren.

Gefahrenbereiche

Gefahrenbereiche sind bekannte Stellen, an denen sich die API geändert hat und Ihr Feld beschädigt werden könnte.

Blockly.Field.register

Felder sind nicht mehr über Blockly.Field.register(); registriert. Es gibt jetzt einen „fieldRegistry“-Namespace, der die Registrierung verarbeitet.

Blockly.Field.register('my_field_name', myFieldClass);

Jetzt:

Blockly.fieldRegistry.register('my_field_name', myFieldClass);

setText

Die setText-Funktion wird nicht mehr vom Blockly-Kern aufgerufen. Wenn Ihre setText-Funktion also Logik enthält, muss sie in die Werteverarbeitungsfunktionen, die getText-Funktion und die Rendering-Funktionen verschoben werden (je nachdem, was genau Ihre setText-Funktion gerade ausführt).

CustomFields.UpgradeField.prototype.setText = function(newText) {
  // Do validation.
  if (typeof newText != 'string' || newText === this.text_) {
    return;
  }

  // Fire event.
  if (this.sourceBlock_ && Blockly.Events.isEnabled()) {
    Blockly.events.fire(new Blockly.Events.BlockChange(
        this.sourceBlock_, 'field', this.name, this.text_, newText
    ));
  }

  // Update text value.
  this.text_ = 'prefix' + newText;

  // Rerender.
  this.size_.width = 0;
};

Jetzt:

CustomFields.UpgradeField.prototype.doClassValidation_ = function(newValue) {
  if (typeof newValue != 'string') {
    return null;
  }
  return newValue;
};

CustomFields.UpgradeField.prototype.getText = function() {
  return  'prefix' + this.value_;
}

Blockly verarbeitet automatisch:

• Es wird geprüft, ob der neue Wert vom alten Wert abweicht.
• Der Wert wird aktualisiert.
• Änderungsereignisse werden ausgelöst.
• Das Feld wird noch einmal gerendert.

Sie haben folgende Aufgaben:

• Wertvalidierung (doClassValidation_).
• Feldtext (getText).
• Benutzeroberfläche für Felder

Hinweis: Wir empfehlen, alle setText-Aufrufe in setValue-Aufrufe zu ändern, da setValue die Validierung unterstützt und setText nicht.

Empfohlene Upgrades

Empfohlene Upgrades sind Orte, an denen die Feld-API geändert wurde. Wenn Sie jedoch keine Änderungen vornehmen, funktioniert das Feld höchstwahrscheinlich weiterhin.

SERIALISIERT

Weitere Informationen zu den Attributen EDITABLE und SERIALIZABLE finden Sie unter Bearbeitbare und serialisierbare Attribute.

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

Die folgende Warnung kann ignoriert werden. Sie lässt sich jedoch beheben, indem Sie das Attribut SERIALIZABLE definieren:

Detected an editable field that was not serializable. Please define
SERIALIZABLE property as true on all editable custom fields. Proceeding
with serialization.

Die obige Warnung bedeutet, dass Blockly glaubt, dass das Feld serialisiert werden soll (weil das Attribut EDITABLE auf „true“ gesetzt ist), aber nicht sicher sein kann, bis Sie das Attribut SERIALIZABLE definieren. Wenn Sie dies ignorieren, funktioniert alles ordnungsgemäß und das Feld wird serialisiert, Sie erhalten jedoch Konsolenwarnungen.

size_.width

this.size_.width = 0;

Jetzt:

this.isDirty_ = true;

Die folgende Warnung kann ignoriert werden. Sie können das Problem beheben, indem Sie das Attribut isDirty_ anstelle des Attributs size_.width festlegen:

Deprecated use of setting size_.width to 0 to rerender a field. Set
field.isDirty_ to true instead.

Die obige Warnung bedeutet, dass Blockly festgestellt hat, dass Sie eine alte Methode zum erneuten Rendern eines Felds verwenden, und dass Sie die neue Methode verwenden möchten.

Weitere Informationen zum Attribut isDirty_ finden Sie unter isDirty_.

init

Die Funktion init wurde in eine Vorlagenfunktion umgewandelt, um doppelten Code in Unterklassen zu reduzieren.

CustomFields.UpgradeField.prototype.init = function() {
  if (this.fieldGroup_) {
    // Already initialized once.
    return;
  }

  // Call superclass.
  CustomFields.UpgradeField.superClass_.init.call(this);

  // Create DOM elements.
  this.extraDom_ = Blockly.utils.dom.createSvgElement('image',
      {
        'height': '10px',
        'width': '10px'
      });
  this.extraDom_.setAttributeNS('http://www.w3.org/1999/xlink',
      'xlink:href', 'image.svg');
  this.extraDom_.style.cursor = 'pointer';
  this.fieldGroup_.appendChild(this.extraDom_);

  // Bind events.
  this.mouseOverWrapper_ =
    Blockly.browserEvents.bind(
        this.getClickTarget_(), 'mouseover', this, this.onMouseOver_);
  this.mouseOutWrapper_ =
    Blockly.browserEvents.bind(
        this.getClickTarget_(), 'mouseout', this, this.onMouseOut_);

  // Render.
  this.setValue(this.getValue());
};

Jetzt:

CustomFields.UpgradeField.prototype.initView = function() {
  CustomFields.UpgradeField.superClass_.initView.call(this);

  this.extraDom_ = Blockly.utils.dom.createSvgElement('image',
      {
        'height': '10px',
        'width': '10px'
      });
  this.extraDom_.setAttributeNS('http://www.w3.org/1999/xlink',
      'xlink:href', 'image.svg');
  this.extraDom_.style.cursor = 'pointer';
  this.fieldGroup_.appendChild(this.extraDom_);
};

CustomFields.UpgradeField.prototype.bindEvents_ = function() {
  CustomFields.UpgradeField.superClass_.bindEvents_.call(this);

  this.mouseOverWrapper_ =
    Blockly.bindEvent_(
        this.getClickTarget_(), 'mouseover', this, this.onMouseOver_);
  this.mouseOutWrapper_ =
    Blockly.bindEvent_(
        this.getClickTarget_(), 'mouseout', this, this.onMouseOut_);
};

Das bedeutet, dass blockly nun automatisch Folgendes verarbeitet:

• Es wird geprüft, ob das Feld bereits initialisiert ist.
• fieldGroup_ wird erstellt.
• Das Feld wird gerendert.
• Kurzinfo zur Bindung und Anzeige von Editor-Ereignissen.

Sie haben folgende Aufgaben:

• Zusätzliche DOM-Elemente (initView) hinzufügen
• Zusätzliche Ereignisbindungen (bindEvents_) hinzufügen.
• Ereignisbindungen (dispose) werden entfernt.

Wichtig: Die gesamte DOM-Erstellung sollte innerhalb von initView erfolgen, da dies am effizientesten ist. Ziehen Sie eine Refaktorierung in Betracht, wenn die DOM-Erstellung im Konstruktor setText, setValue oder render_ stattfindet.

onMouseDown_

CustomFields.UpgradeField.prototype.onMouseDown_ = function(e) {
  // ...
};

Jetzt:

CustomFields.UpgradeField.prototype.showEditor_ = function() {
  // ...
}

Wir empfehlen, die Funktion showEditor_ für die Verarbeitung von Mausklicks und nicht die Funktion onMouseDown_ zu überschreiben, da dies die Eingabe durch das Gestensystem ermöglicht.

Weitere Informationen zu Bearbeitern finden Sie unter Bearbeiter.

setValue

Die setValue-Funktion ist jetzt eine Vorlagenfunktion, mit der duplizierte Codeinhalte in Unterklassen reduziert werden. Wenn Ihre setValue-Funktion Logik enthält, sollten Sie sie so refaktorieren, dass sie den unter Wertbehandlung beschriebenen Pfaden zur Wertbehandlung entspricht.

text_

Wir empfehlen, niemals direkt auf das Attribut text_ Ihres Felds zuzugreifen oder es zu aktualisieren. Verwenden Sie stattdessen die Funktion getText, um auf den für Nutzer lesbaren Text Ihres Felds zuzugreifen, und die Funktion setValue, um den gespeicherten Wert des Felds zu aktualisieren.

Weitere Informationen zum Wert eines Felds im Vergleich zu seinem Text finden Sie unter Aufbau eines Felds.

Unterstützung beim Upgrade erhalten

Hinweis :Bevor Sie Unterstützung beim Upgrade anfordern, versuchen Sie, Ihr Feld mithilfe der bereitgestellten Informationen selbstständig zu aktualisieren.

Was Sie angeben sollten

Wenn Sie um Unterstützung bitten, stellen Sie am besten konkrete Fragen:

Nicht empfohlen: „Was stimmt mit diesem Feld nicht?“

Auch nicht empfohlen: „Hilfe beim Upgrade dieses Feldes.“

Empfohlen: „Feldtext wird nicht korrekt aktualisiert.“

Es ist auch erforderlich, den Menschen, die Ihnen helfen, Ressourcen zur Verfügung zu stellen. Diese Dateien sollten für andere einfach zu verwenden sein.

Nicht empfohlen:

• Bilder von Code
• Der Code ist unvollständig.

Empfohlen:

• Vollständiger Feldcode im Textformat.
• Bilder von GIFs mit schlechtem Feldverhalten.
• Schritte, um schlechtes Verhalten auf dem Feld zu reproduzieren.
• Die Version von Blockly, von der Sie ein Upgrade ausführen.

Ort der Veröffentlichung

Stellen Sie Fragen zum Upgrade im blockly-Entwicklerforum.

Wenn Sie sicher sind, dass es sich um ein Problem mit dem Blockly Core handelt, können Sie auch ein Problem auf dem blockierenden GitHub posten. Wenn Sie ein Problem posten möchten, geben Sie alle angeforderten Informationen ein.