研究调查问卷：请告诉我们您使用 Blockly 的体验

此页面由 Cloud Translation API 翻译。

升级自定义字段

2019 年 7 月（版本 2.20190722）新增了一个编码规范程度更高的字段 API。它旨在尽可能向后兼容也就是说，如果您创建了自定义字段很有可能继续正常工作。在决定是否需要升级自定义字段之前，您应该先阅读填写危险区域部分，并对您所在的区域进行全面测试。

因为在 2019 年 7 月之前，各个字段之间未进行标准化很难涵盖开发者可能需要进行的所有更改。本文档试图涵盖所有可能的更改，但如果本文档并未涵盖，介绍您感兴趣的内容，请阅读获取升级协助。

危险区域

危险区域是已知 API 发生变化的地方，损坏。

Blockly.Field.register

这些字段不再通过 Blockly.Field.register(); 注册。还有现在是处理注册的 fieldRegistry 命名空间

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

会变为：

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

setText

Blockly 核心不再调用 setText 函数，因此，如果您的 setText 函数包含需要移至值处理一组函数，即 getText 函数和渲染函数（具体取决于您的 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;
};

会变为：

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

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

Blockly 会自动处理：

检查新值是否与旧值不同。
正在更新值。
触发更改事件。
重新渲染字段。

您需要处理：

值验证 (doClassValidation_)。
字段文本 (getText)。
字段界面

。

推荐的升级

建议升级的地方是字段 API 已更改，但如果您选择不进行更改，您的字段很可能仍可正常使用。

可量化

如需详细了解 EDITABLE 和 SERIALIZABLE 属性，请参阅可修改且可序列化的属性。

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

以下警告可以忽略，但您可以通过定义 SERIALIZABLE 属性：

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

上面的警告表示 Blockly 认为您需要字段（因为 EDITABLE 属性为 true），但是然后才能确定 SERIALIZABLE 属性。如果您选择不进行此类处理，一切运行正常，序列化，但是您会收到控制台警告。

size_.width

this.size_.width = 0;

会变为：

this.isDirty_ = true;

以下警告可以忽略，但您可以通过设置 isDirty_ 属性，而不是 size_.width 属性：

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

上面的警告表示 Blockly 检测到您在使用旧方法重新渲染字段，并希望使用新方法。

有关 isDirty_ 属性的更多信息，请参阅 isDirty_.

init

init 函数已制作成模板函数更改为减少子类中的重复代码。

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

会变为：

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

这意味着，blockly 现在会自动处理：

检查该字段是否已初始化。
创建 fieldGroup_。
呈现字段。
绑定提示并显示编辑器事件。

您需要处理：

添加更多 DOM 元素 (initView)。
添加更多事件绑定 (bindEvents_)：
处置事件绑定 (dispose)。

。

onMouseDown_

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

会变为：

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

我们建议您替换 showEditor_ 函数来处理鼠标而不是 onMouseDown_ 函数，因为该函数允许输入通过手势系统。

如需详细了解编辑者，请参阅编辑者。

setValue

setValue 函数现在是模板函数更改为减少子类中的重复代码。如果您的 setValue 函数包含逻辑，请考虑重构它，以适应值处理。

text_

我们建议您切勿访问或更新应用的 text_ 属性，字段。而应使用 getText 函数访问字段的用户可读文本 setValue 函数以更新字段的存储值。

有关字段值及其文本的详细信息，请参阅字段剖析。

获取升级协助

需要提供的内容

寻求帮助时，最好提出具体问题：

不推荐：“此字段有什么问题？”

另外不建议的做法：“帮我升级此字段”。

建议：“字段文本未正确更新。”

您还需要向为您提供帮助的人提供相关资源。这些文件也应易于他人使用。

不推荐：

代码图片。
代码不完整。

发帖位置

如有任何关于升级的问题，请访问已屏蔽开发者网站论坛。

如果您确定问题是阻塞核心导致的，则可以用户还会发布问题。如果您决定发布问题，请填写所有请求的信息。