升级自定义字段

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)。
• 字段界面

。

注意 ：我们建议您将所有 setText 调用更改为 setValue 调用，因为 setValue 支持验证，而 setText 不支持。

推荐的升级

建议升级的地方是字段 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)。

。

重要提示： 所有 DOM 创建都应在 initView 内完成，因为 效率。如果您在 构造函数、setText、setValue 或 render_。

onMouseDown_

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

会变为：

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

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

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

setValue

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

text_

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

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

获取升级协助

注意 ：在寻求升级帮助之前，请先将您的 字段。

需要提供的内容

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

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

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

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

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

不推荐：

• 代码图片。
• 代码不完整。

推荐：

• 以文本格式填写字段代码。
• 错误字段行为的 GIF 图片。
• 重现不良字段行为的步骤。
• 要升级的 blockly 版本。

发帖位置

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

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