Actualiza un campo personalizado

En julio de 2019 (versión 2.20190722), se agregó una API de campos más codificada. Se diseñó para ser lo más retrocompatible posible. Esto significa que, si creaste un campo personalizado antes de julio de 2019, es muy probable que siga funcionando. Antes de decidir si tu campo personalizado necesita una actualización, debes leer la sección Áreas de riesgo y probar tu campo a fondo.

Dado que no había una estandarización entre los campos antes de julio de 2019, es difícil abarcar todos los cambios que un desarrollador podría necesitar realizar. En este documento, se intentan abarcar todos los cambios posibles, pero, si no se incluye algo que te interesa, lee la sección sobre cómo obtener asistencia para la actualización.

Nota: Si tienes una pequeña cantidad de campos personalizados, puede ser más fácil reescribirlos con las instrucciones de creación de campos personalizados, en lugar de intentar actualizarlos de forma gradual.

Áreas de peligro

Las áreas de peligro son lugares conocidos en los que la API cambió y tu campo podría estar dañado.

Blockly.Field.register

Los campos ya no se registran a través de Blockly.Field.register();. Ahora hay un espacio de nombres fieldRegistry que controla el registro.

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

Se convierte en lo siguiente:

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

setText

El núcleo de Blockly ya no llama a la función setText, por lo que, si tu función setText contiene lógica, deberá trasladarse al conjunto de funciones de control de valores, la función getText y las funciones de renderización (según lo que haga exactamente tu función 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;
};

Se convierte en lo siguiente:

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

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

Blockly controla automáticamente lo siguiente:

• Comprobar si el valor nuevo es diferente del valor anterior
• Se está actualizando el valor.
• Se activan eventos de cambio.
• Se vuelve a renderizar el campo.

Deberás encargarte de lo siguiente:

• Validación de valores (doClassValidation_).
• Texto del campo (getText).
• IU de campos

Nota: Te recomendamos que cambies todas las llamadas a setText por llamadas a setValue, ya que setValue admite la validación y setText no.

Mejoras recomendadas

Las actualizaciones recomendadas son lugares en los que se cambió la API de campos, pero, si decides no realizar cambios, es muy probable que tu campo siga funcionando.

SERIALIZABLE

Para obtener más información sobre las propiedades EDITABLE y SERIALIZABLE, consulta Propiedades editables y serializables.

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

Puedes ignorar la siguiente advertencia, pero puedes resolverla definiendo la propiedad SERIALIZABLE:

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

La advertencia anterior significa que Blockly cree que deseas que el campo se serialice (porque la propiedad EDITABLE es verdadera), pero no puede estar seguro hasta que definas la propiedad SERIALIZABLE. Si decides no hacer nada, todo funcionará correctamente y tu campo se serializará, pero recibirás advertencias en la consola.

size_.width

this.size_.width = 0;

Se convierte en lo siguiente:

this.isDirty_ = true;

Puedes ignorar la siguiente advertencia, pero puedes resolverla configurando la propiedad isDirty_ en lugar de la propiedad size_.width:

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

La advertencia anterior significa que Blockly detectó que estás usando un método antiguo para volver a renderizar un campo y te recomienda que uses el método nuevo.

Para obtener más información sobre la propiedad isDirty_, consulta isDirty_.

init

La función init se convirtió en una función de plantilla para reducir el código duplicado en las subclases.

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

Se convierte en lo siguiente:

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

Esto significa que Blockly ahora controla automáticamente lo siguiente:

• Verifica si el campo ya se inicializó.
• Se está creando el fieldGroup_.
• Renderiza el campo.
• Vincula la sugerencia y muestra los eventos del editor.

Deberás encargarte de lo siguiente:

• Agregar elementos DOM adicionales (initView)
• Agregar vinculaciones de eventos adicionales (bindEvents_)
• Descartar vinculaciones de eventos (dispose)

Importante: Toda la creación del DOM debe realizarse dentro de initView, ya que es lo más eficiente. Considera refactorizar si la creación del DOM se realiza dentro del constructor, setText, setValue o render_.

onMouseDown_

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

Se convierte en lo siguiente:

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

Te recomendamos que anules la función showEditor_ para controlar los clics del mouse en lugar de la función onMouseDown_, ya que esto permite que la entrada pase por el sistema de gestos.

Para obtener más información sobre los editores, consulta Editores.

setValue

La función setValue ahora es una función de plantilla para reducir el código duplicado en las subclases. Si tu función setValue contiene lógica, considera refactorizarla para que se ajuste a las rutas de control de valores que se describen en Control de valores.

text_

Te recomendamos que nunca accedas a la propiedad text_ de tu campo ni la actualices directamente. En su lugar, usa la función getText para acceder al texto legible para el usuario de tu campo y la función setValue para actualizar el valor almacenado de tu campo.

Para obtener más información sobre el valor de un campo en comparación con su texto, consulta Anatomía de un campo.

Cómo obtener asistencia para la actualización

Nota: Antes de solicitar asistencia para la actualización, haz todo lo posible para actualizar tu campo de forma independiente con la información proporcionada.

Qué debes proporcionar

Cuando solicites asistencia, lo mejor es que hagas preguntas específicas:

No se recomienda: "¿Cuál es el problema con este campo?"

Tampoco se recomienda: "Ayúdame a actualizar este campo".

Recomendado: "El texto del campo no se actualiza correctamente".

También es necesario proporcionar recursos a las personas que te asisten. Estos archivos deben ser fáciles de usar para otras personas.

No se recomienda:

• Imágenes de código
• El código está incompleto.

Recomendado:

• Código de campo completo en formato de texto.
• Imágenes de GIFs de comportamiento inadecuado en el campo.
• Pasos para reproducir el comportamiento incorrecto del campo.
• Es la versión de Blockly desde la que se realiza la actualización.

Dónde publicar

Publica preguntas sobre la actualización en el foro de desarrolladores de Blockly.

Si tienes la certeza de que el problema se debe al núcleo de Blockly, también puedes publicar un problema en el GitHub de Blockly. Si decides publicar un problema, completa toda la información solicitada.