Mise à niveau d'un champ personnalisé

En juillet 2019 (version 2.20190722) Une API avec champs plus codifiés a été ajoutée. Il est destiné à être aussi rétrocompatible que possible. Cela signifie que si vous aviez créé champ personnalisé avant juillet 2019, il devrait continuer à fonctionner. Avant de décider si votre champ personnalisé doit être mis à jour, consultez la page consultez la section Zones à risque et testez-les minutieusement.

Parce qu'il y avait un manque de standardisation entre les champs avant juillet 2019 il est délicat de couvrir toutes les modifications qu'un développeur pourrait avoir besoin d'apporter. Ce document tente de couvrir toutes les modifications probables, mais si ce n'est pas le cas, aborder un sujet qui vous intéresse, lisez la section sur obtenir de l'aide pour passer à une édition supérieure.

Remarque :Si vous disposez d'un petit nombre de champs personnalisés, il peut être plus simple de simplement réécrivez-les en suivant les instructions de création des champs personnalisés, plutôt que d'essayer de les migrer au coup par coup.

Zones dangereuses

Les zones dangereuses sont des lieux connus où l'API a changé, et votre champ peut être cassées.

Blockly.Field.register

Les champs ne sont plus enregistrés via Blockly.Field.register();. Il y a et un espace de noms fieldRegistry qui gère l'enregistrement.

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

Devient:

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

setText

La fonction setText n'est plus appelée par le noyau Blockly. Par conséquent, si votre setText contient une logique. Vous devez la déplacer vers gestion de la valeur suite de fonctions, getText et les fonctions de rendu (en fonction de ce que fait exactement votre fonction setText).

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

Devient:

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

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

Blockly gère automatiquement les éléments suivants:

• Vérifiez si la nouvelle valeur est différente de l'ancienne.
• Mise à jour de la valeur...
• Déclenchement des événements de modification
• Affichage à nouveau du champ.

Vous devrez gérer:

• Validation de la valeur (doClassValidation_).
• Texte du champ (getText).
• Interface utilisateur des champs

Remarque :Nous vous recommandons de modifier les appels setText pour setValue, car setValue prend en charge la validation, contrairement à setText.

Mises à jour recommandées

Les mises à niveau recommandées sont les endroits où l'API de champ a été modifiée, mais si vous si vous décidez de ne pas apporter de modifications, votre champ fonctionnera probablement tout de même.

SÉRIALISABLE

Pour en savoir plus sur les propriétés EDITABLE et SERIALIZABLE, consultez Propriétés modifiables et sérialisables.

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

Vous pouvez ignorer l'avertissement ci-dessous, mais vous pouvez le résoudre en définissant SERIALIZABLE :

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

L'avertissement ci-dessus signifie que Blockly pense que vous souhaitez doit être sérialisé (car la propriété EDITABLE est "true"), mais ne peut pas être fiable tant que vous n'avez pas défini la propriété SERIALIZABLE. Si vous choisissez ne rien modifier, et tout fonctionnera correctement sérialisées, mais vous recevrez des avertissements dans la console.

size_.width

this.size_.width = 0;

Devient:

this.isDirty_ = true;

Vous pouvez ignorer l'avertissement ci-dessous, mais vous pouvez le résoudre en définissant isDirty_ au lieu de la propriété size_.width:

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

L'avertissement ci-dessus signifie que Blockly a détecté que vous utilisiez une ancienne méthode pour réafficher un et nous aimerions que vous utilisiez la nouvelle méthode.

Pour en savoir plus sur la propriété isDirty_, consultez isDirty_.

init

La fonction init a été transformée en modèle réduire le code en double dans les sous-classes.

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

Devient:

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

Cela signifie que Blockly gère désormais automatiquement les éléments suivants:

• Vérifiez si le champ est déjà initialisé.
• Créer le fieldGroup_
• Affichage du champ.
• Info-bulle de la liaison et affichage des événements de l'éditeur.

Vous devrez gérer:

• Ajout d'un autre Éléments DOM (initView).
• Ajout d'un autre liaisons d'événements (bindEvents_).
• Suppression des liaisons d'événements (dispose).

Important :Toute création DOM doit être effectuée dans initView, car il s'agit efficace. Envisagez une refactorisation si vous créez un DOM à l'intérieur du constructeur, setText, setValue ou render_.

onMouseDown_

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

Devient:

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

Nous vous recommandons de remplacer la fonction showEditor_ pour gérer la souris au lieu de la fonction onMouseDown_, car elle permet à l'entrée de transmettre grâce au système de gestes.

Pour en savoir plus sur les éditeurs, consultez Éditeurs.

setValue

La fonction setValue est désormais un modèle réduire le code en double dans les sous-classes. Si votre fonction setValue contient une logique, envisagez de le refactoriser pour l'adapter aux chemins de gestion des valeurs décrits dans Gestion de la valeur :

text_

Nous vous recommandons de ne jamais consulter ni mettre à jour la propriété text_ de votre directement. Utilisez plutôt la méthode Fonction getText pour accéder au texte de votre champ lisible par l'utilisateur. Fonction setValue pour mettre à jour la valeur stockée dans votre champ.

Pour en savoir plus sur la valeur d'un champ par rapport à son texte, consultez Anatomie d'un champ.

Obtenir de l'aide pour la mise à niveau

Remarque :Avant de demander de l'aide pour la mise à niveau, de manière indépendante, à l'aide des informations fournies.

Informations à fournir

Lorsque vous demandez de l'aide, il est préférable de poser des questions spécifiques:

Déconseillé : "Quel est le problème avec ce champ ?"

Autre recommandation déconseillée : "Aidez-moi à mettre à jour ce champ".

Recommandation : "Le texte du champ n'est pas mis à jour correctement."

Il est également nécessaire de fournir des ressources aux personnes qui vous aident. Ces les fichiers doivent être faciles à utiliser pour les autres.

Option déconseillée :

• Images du code.
• Code incomplet.

Recommandations :

• Code de champ complet au format texte.
• Images de GIF illustrant un comportement insatisfaisant
• Étapes permettant de reproduire un comportement de champ incorrect.
• Version de Blockly à partir de laquelle vous effectuez la mise à niveau.

Emplacement de publication

Publiez vos questions sur la mise à niveau sur le site de développeur forum.

Si vous êtes certain que le problème provient du noyau blockly, vous pouvez également publier un problème sur GitHub. Si vous décidez de publier un problème, veuillez remplir tous les les informations demandées.