Mettre à niveau un champ personnalisé

En juillet 2019 (version 2.20190722), une API de champs plus codifiée a été ajoutée. Il est conçu pour être aussi rétrocompatible que possible. Cela signifie que si vous avez créé un champ personnalisé avant juillet 2019, il continuera probablement de fonctionner. Avant de décider si votre champ personnalisé doit être mis à niveau, lisez la section Points critiques et testez minutieusement votre champ.

Étant donné que les champs n'étaient pas standardisés avant juillet 2019, il est difficile de couvrir toutes les modifications qu'un développeur peut avoir besoin d'apporter. Ce document tente de couvrir tous les changements probables. Toutefois, si vous ne trouvez pas la réponse à votre question, veuillez lire la section sur l'obtention d'aide pour la mise à niveau.

Remarque : Si vous n'avez qu'un petit nombre de champs personnalisés, il peut être plus simple de les réécrire en suivant les instructions de création de champs personnalisés plutôt que d'essayer de les mettre à niveau un par un.

Zones dangereuses

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

Blockly.Field.register

Les champs ne sont plus enregistrés via Blockly.Field.register();. Il existe désormais 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 cœur de Blockly. Par conséquent, si votre fonction setText contient une logique, elle devra être déplacée vers la suite de fonctions de gestion des valeurs, la fonction getText et les fonctions de rendu (selon 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 d'événements de modification.
• Le champ est à nouveau affiché.

Vous devrez gérer les éléments suivants :

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

Remarque : Nous vous recommandons de remplacer tous les appels setText par des appels setValue, car setValue est compatible avec la validation, contrairement à setText.

Mises à jour recommandées

Les mises à niveau recommandées sont des endroits où l'API de champ a été modifiée, mais si vous choisissez de ne pas apporter de modifications, votre champ fonctionnera probablement toujours.

SERIALIZABLE

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 la propriété 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 que le champ soit sérialisé (car la propriété EDITABLE est définie sur "true"), mais il ne peut pas en être sûr tant que vous n'avez pas défini la propriété SERIALIZABLE. Si vous choisissez de ne pas le modifier, tout fonctionnera correctement et votre champ sera sérialisé, 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 la propriété 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 utilisez une ancienne méthode pour réafficher un champ et vous invite à utiliser la nouvelle méthode.

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

init

La fonction init a été transformée en fonction de modèle pour 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érifie si le champ est déjà initialisé.
• Créez le fieldGroup_.
• Afficher le champ.
• Info-bulle de liaison et affichage des événements de l'éditeur.

Vous devrez gérer les éléments suivants :

• Ajout d'éléments DOM supplémentaires (initView).
• Ajout de liaisons d'événements supplémentaires (bindEvents_).
• Suppression des liaisons d'événements (dispose).

Important : Toute création de DOM doit être effectuée dans initView, car c'est la méthode la plus efficace. Envisagez de refactoriser si vous créez des éléments DOM dans le 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_ par la fonction onMouseDown_ pour gérer les clics de souris, car cela permet à l'entrée de passer par le système de gestes.

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

setValue

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

text_

Nous vous recommandons de ne jamais accéder directement à la propriété text_ de votre champ ni la modifier. Utilisez plutôt la fonction getText pour accéder au texte lisible par l'utilisateur de votre champ et la fonction setValue pour mettre à jour la valeur stockée de 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, essayez de mettre à niveau votre champ de manière autonome en utilisant les 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 ?"

Nous vous déconseillons également d'utiliser la requête "Aide-moi à mettre à niveau ce champ".

Recommandation : "Le texte du champ ne se met pas à jour correctement."

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

Option déconseillée :

• Images de code
• Code incomplet.

Recommandations :

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

Où publier

Posez vos questions sur la mise à niveau sur le forum des développeurs Blockly.

Si vous êtes sûr que le problème est lié au cœur de Blockly, vous pouvez également publier un problème sur le GitHub de Blockly. Si vous décidez de signaler un problème, veuillez fournir toutes les informations demandées.