Benutzerdefiniertes Feld aktualisieren

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

Da die Felder vor Juli 2019 nicht standardisiert waren, ist es schwierig, alle Änderungen zu berücksichtigen, die ein Entwickler möglicherweise vornehmen muss. In diesem Dokument werden alle wahrscheinlichen Änderungen behandelt. Wenn Sie jedoch etwas wissen möchten, das hier nicht beschrieben wird, lesen Sie den Abschnitt Unterstützung beim Upgrade erhalten.

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

Gefahrenbereiche

Gefahrenbereiche sind bekannte Orte, an denen sich die API geändert hat und Ihr Feld möglicherweise nicht mehr funktioniert.

Blockly.Field.register

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

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

Wird zu:

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

setText

Die Funktion setText wird nicht mehr vom Blockly-Kern aufgerufen. Wenn Ihre setText-Funktion also Logik enthält, muss diese in die Funktionsgruppe Wertverarbeitung, die Funktion getText und die Rendering-Funktionen verschoben werden (je nachdem, was Ihre setText-Funktion genau macht).

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;
};

Wird zu:

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

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

Blockly übernimmt automatisch folgende Aufgaben:

• Prüfen, ob sich der neue Wert vom alten Wert unterscheidet.
• Der Wert wird aktualisiert.
• Änderungsereignisse auslösen
• Das Feld wird noch einmal gerendert.

Sie müssen Folgendes berücksichtigen:

• Wertvalidierung (doClassValidation_):
• Feldtext (getText):
• Feld-UI

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

Empfohlene Upgrades

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

SERIALIZABLE

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 können sie 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 Warnung oben bedeutet, dass Blockly davon ausgeht, dass Sie das Feld serialisieren möchten (da die Eigenschaft EDITABLE auf „true“ gesetzt ist). Blockly kann sich jedoch erst sicher sein, wenn Sie die Eigenschaft SERIALIZABLE definieren. Wenn Sie diese Option nicht ändern, funktioniert alles ordnungsgemäß und Ihr Feld wird serialisiert. Sie erhalten jedoch Konsolenwarnungen.

size_.width

this.size_.width = 0;

Wird zu:

this.isDirty_ = true;

Die folgende Warnung kann ignoriert werden. Sie können sie jedoch beheben, indem Sie die Property isDirty_ anstelle der Property 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 erkannt hat, dass Sie eine alte Methode zum erneuten Rendern eines Felds verwenden, und Sie auffordert, die neue Methode zu verwenden.

Weitere Informationen zum Attribut isDirty_ finden Sie unter isDirty_.

init

Die Funktion init wurde in eine Vorlagenfunktion umgewandelt, um doppelten Code in untergeordneten Klassen 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());
};

Wird zu:

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 jetzt automatisch Folgendes übernimmt:

• Prüfen, ob das Feld bereits initialisiert ist.
• fieldGroup_ wird erstellt.
• Das Feld wird gerendert.
• Bindungs-Kurzinfo und Editor-Ereignisse anzeigen

Sie müssen Folgendes berücksichtigen:

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

Wichtig :Die gesamte DOM-Erstellung sollte in initView erfolgen, da dies am effizientesten ist. Erwägen Sie ein Refactoring, wenn DOM-Elemente im Konstruktor, in setText, setValue oder render_ erstellt werden.

onMouseDown_

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

Wird zu:

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

Wir empfehlen, die showEditor_-Funktion zu überschreiben, um Mausklicks zu verarbeiten, anstatt die onMouseDown_-Funktion, da so die Eingabe durch das Gestensystem weitergeleitet werden kann.

Weitere Informationen zu Editoren finden Sie unter Editoren.

setValue

Die Funktion setValue ist jetzt eine Vorlagenfunktion, um doppelten Code in Unterklassen zu reduzieren. Wenn Ihre setValue-Funktion Logik enthält, sollten Sie sie so umgestalten, dass sie den in Wertverarbeitung beschriebenen Pfaden für die Wertverarbeitung entspricht.

text_

Wir empfehlen, niemals direkt auf die Property text_ Ihres Felds zuzugreifen oder sie 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 Ihres Felds zu aktualisieren.

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

Unterstützung beim Upgrade

Hinweis :Bevor Sie um Unterstützung bei der Aktualisierung bitten, versuchen Sie bitte, das Feld selbstständig anhand der bereitgestellten Informationen zu aktualisieren.

Was Sie angeben müssen

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

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

Ebenfalls nicht empfehlenswert: „Hilf mir, dieses Feld zu aktualisieren.“

Empfohlen: „Feldtext wird nicht richtig aktualisiert.“

Außerdem müssen Sie den Personen, die Ihnen helfen, Ressourcen zur Verfügung stellen. Diese Dateien sollten für andere einfach zu verwenden sein.

Nicht empfohlen:

• Bilder von Code
• Unvollständiger Code.

Empfohlen:

• Vervollständigen Sie den Feldcode in einem Textformat.
• Bilder oder GIFs von unerwünschtem Verhalten auf dem Spielfeld.
• Schritte zum Reproduzieren des unerwünschten Feldverhaltens.
• Die Version von Blockly, von der Sie ein Upgrade durchführen.

Wo posten?

Posten Sie Fragen zum Upgrade im Blockly-Entwicklerforum.

Wenn Sie sicher sind, dass das Problem mit dem Blockly-Kern zusammenhängt, können Sie auch ein Problem auf GitHub melden. Wenn Sie ein Problem melden möchten, füllen Sie bitte alle erforderlichen Felder aus.