Actualiza un campo personalizado

En julio de 2019 (versión 2.20190722) se agregó una API de campos más codificados. Tiene como objetivo lo más retrocompatible posible. Esto significa que si hubieras creado campo personalizado antes de julio de 2019, es probable que siga funcionando. Antes de decidir si tu campo personalizado debe actualizarse, debes leer en la sección Áreas de peligro y realiza pruebas exhaustivas en tu campo.

Porque hubo una falta de estandarización entre los campos antes de julio de 2019. no es fácil abarcar todos los cambios que un desarrollador debería realizar. Este documento intenta abarcar todos los cambios probables, pero si este documento no para abordar temas que te interesan, lee la sección sobre cómo obtener asistencia con la actualización.

Nota: Si tienes pocos campos personalizados, tal vez sea más fácil volver a escribirlos con las instrucciones para crear campos personalizados en lugar de intentar actualizarlos por partes.

Áreas de peligro

Las áreas de peligro son lugares conocidos donde la API cambió, y tu campo podría está roto.

Blockly.Field.register

Los campos ya no están registrados a través de Blockly.Field.register();. Hay ahora es 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 setText de la función contiene lógica, deberás moverla al manejo de valores paquete de funciones, el método getText y las funciones de renderización (según lo que haga exactamente la 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:

• Verifica si el valor nuevo es diferente al anterior.
• Actualizando el valor.
• Activando eventos de cambio
• Se volverá a renderizar el campo.

Deberás controlar lo siguiente:

• Validación del valor (doClassValidation_).
• Campo de texto (getText):
• IU de campo

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

Mejoras recomendadas

Las actualizaciones recomendadas son lugares en los que se cambió la API del campo, pero si opta por no hacer cambios, lo más probable es que tu campo aún funcione.

SERIALIZABLE

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

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

La siguiente advertencia se puede omitir, pero puedes resolverla definiendo el SERIALIZABLE. propiedad:

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 quieres se serializan (porque la propiedad EDITABLE es verdadera), pero No puedes estar seguro hasta que definas la propiedad SERIALIZABLE. Si eliges Deja esto en paz, todo funcionará de forma correcta, y tu campo será pero recibirás advertencias de la consola.

size_.width

this.size_.width = 0;

Se convierte en lo siguiente:

this.isDirty_ = true;

La siguiente advertencia no se puede omitir, pero puedes resolverla si configuras 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 y quieres usar el nuevo método.

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

init

La función init se convirtió en una plantilla función en 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:

• Comprueba si el campo ya se inicializó.
• Crea el fieldGroup_.
• Renderiza el campo.
• Cuadro de información de vinculación y eventos de editor de programa.

Deberás controlar lo siguiente:

• Agregar Elementos del DOM (initView).
• Agregar vinculaciones de eventos (bindEvents_).
• Eliminación de vinculaciones de eventos (dispose).

Importante: Toda la creación del DOM debe realizarse dentro de initView, ya que este es el eficiente. Considera refactorizar si tienes que crear un DOM 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 anular la función showEditor_ para controlar el mouse. en lugar de la función onMouseDown_, ya que permite que la entrada pase a través del sistema de gestos.

Para obtener más información al respecto, consulta Editores.

setValue

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

text_

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

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

Cómo obtener asistencia con la actualización

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

Qué debes proporcionar

Cuando solicites asistencia, es mejor hacer preguntas específicas:

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

También no 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 los archivos deben ser fáciles de usar para otros.

No se recomienda lo siguiente:

• Imágenes de código
• Código incompleto.

Recomendado:

• Completa el código de campo en formato de texto.
• Imágenes de GIFs de comportamiento inadecuado del campo.
• Pasos para reproducir un comportamiento de campo inadecuado
• Es la versión de Blockly desde la cual estás actualizando.

Dónde publicar

Publica preguntas sobre la actualización en el bloqueo de desarrollador. foro.

Si estás seguro de que se trata de un problema con el núcleo bloqueado, puedes también publican un problema en el bloque de GitHub. Si decides publicar un problema, completa todos los campos la información solicitada.