创建新的字段类型

在创建新的字段类型之前,请考虑用于自定义字段的其他方法是否符合您的需求。如果您的应用需要存储新的值类型,或者您希望为现有的值类型创建新的界面,则可能需要创建新的字段类型。

如需创建新字段,请执行以下操作:

  1. 实现构造函数
  2. 注册 JSON 密钥并实现 fromJson
  3. 处理块界面和事件监听器的初始化
  4. 处理事件监听器的处置(系统会为您处理界面)。
  5. 实现值处理
  6. 添加字段值的文本表示形式,以实现无障碍功能
  7. 添加其他功能,例如:
  8. 配置字段的其他方面,例如:

本部分假定您已阅读并熟悉字段剖析中的内容。

如需查看自定义字段的示例,请参阅自定义字段演示

实现构造函数

字段的构造函数负责设置字段的初始值,并视需要设置本地验证器。在源块初始化期间,系统会调用自定义字段的构造函数,无论源块是使用 JSON 还是 JavaScript 定义的。因此,自定义字段在构建期间无权访问源块。

以下代码示例会创建一个名为 GenericField 的自定义字段:

class GenericField extends Blockly.Field {
  constructor(value, validator) {
    super(value, validator);

    this.SERIALIZABLE = true;
  }
}

方法签名

字段构造函数通常接受值和本地验证器。该值是可选的,如果您不传递值(或传递的值未通过类验证),系统将使用父类的默认值。对于默认 Field 类,该值为 null。如果您不想使用该默认值,请务必传递一个合适的值。验证程序参数仅适用于可修改字段,并且通常标记为可选。如需详细了解验证程序,请参阅验证器文档

结构

构造函数内的逻辑应遵循以下流程:

  1. 调用继承的超级构造函数(所有自定义字段应继承自 Blockly.Field 或其某个子类),以正确初始化该值并为字段设置本地验证器。
  2. 如果您的字段可序列化,请在构造函数中设置相应的属性。可修改字段必须可序列化,并且字段默认可修改,因此除非您知道此属性不应该可序列化,否则应该将此属性设置为 true。
  3. 可选:应用其他自定义设置(例如,标签字段允许传递一个 css 类,该类随后会应用于文本)。

JSON 和注册

JSON 块定义中,字段由字符串(例如 field_numberfield_textinput)描述。块式维护从这些字符串到字段对象的映射,并在构造期间对相应对象调用 fromJson

调用 Blockly.fieldRegistry.register 以将您的字段类型添加到此映射,并传入字段类作为第二个参数:

Blockly.fieldRegistry.register('field_generic', GenericField);

您还需要定义 fromJson 函数。您的实现应首先使用 replaceMessageReferences 取消引用任何字符串表引用,然后将值传递给构造函数。

GenericField.fromJson = function(options) {
  const value = Blockly.utils.parsing.replaceMessageReferences(
      options['value']);
  return new CustomFields.GenericField(value);
};

正在初始化

构建字段时,它基本上仅包含一个值。初始化包括构建 DOM、构建模型(如果该字段具有模型)以及绑定事件。

On-Block 显示

在初始化期间,您负责创建字段的块显示所需的任何内容。

默认值、背景和文本

默认的 initView 函数会创建一个浅色 rect 元素和一个 text 元素。如果您希望字段同时具有这两个标签和一些额外的功能,请先调用父类 initView 函数,然后再添加其余的 DOM 元素。如果您希望字段包含一个(而不是两个)这两个元素,可以使用 createBorderRect_createTextElement_ 函数。

自定义 DOM 构造

如果您的字段是通用文本字段(例如 Text Input),系统将为您处理 DOM 构造。否则,您需要替换 initView 函数以创建将来渲染字段时所需的 DOM 元素。

例如,下拉菜单字段可能同时包含图片和文字。在 initView 中,它会创建单个图片元素和单个文本元素。然后,在 render_ 期间,它会根据所选选项的类型显示活动元素并隐藏另一个元素。

DOM 元素的创建方式既可以使用 Blockly.utils.dom.createSvgElement 方法,也可以使用传统的 DOM 创建方法完成。

字段的块显示要求如下:

  • 所有 DOM 元素都必须是字段 fieldGroup_ 的子级。系统会自动创建字段组。
  • 所有 DOM 元素都必须位于所报告的字段尺寸范围内。

如需详细了解如何自定义和更新块显示方式,请参阅渲染部分。

添加文本符号

如果要向字段的文本添加符号(例如 Angle 字段的度数符号),可以将符号元素(通常包含在 <tspan> 中)直接附加到该字段的 textElement_

输入事件

默认情况下,字段会注册提示事件和 mousedown 事件(用于显示编辑器)。如果您想监听其他类型的事件(例如,如果您想处理对某个字段的拖动),则应替换该字段的 bindEvents_ 函数。

bindEvents_() {
  // Call the superclass function to preserve the default behavior as well.
  super.bindEvents_();

  // Then register your own additional event listeners.
  this.mouseDownWrapper_ =
  Blockly.browserEvents.conditionalBind(this.getClickTarget_(), 'mousedown', this,
      function(event) {
        this.originalMouseX_ = event.clientX;
        this.isMouseDown_ = true;
        this.originalValue_ = this.getValue();
        event.stopPropagation();
      }
  );
  this.mouseMoveWrapper_ =
    Blockly.browserEvents.conditionalBind(document, 'mousemove', this,
      function(event) {
        if (!this.isMouseDown_) {
          return;
        }
        var delta = event.clientX - this.originalMouseX_;
        this.setValue(this.originalValue_ + delta);
      }
  );
  this.mouseUpWrapper_ =
    Blockly.browserEvents.conditionalBind(document, 'mouseup', this,
      function(_event) {
        this.isMouseDown_ = false;
      }
  );
}

如需绑定到事件,您通常应该使用 Blockly.utils.browserEvents.conditionalBind 函数。这种绑定事件的方法会在拖动操作期间过滤掉辅助触摸。如果您希望处理程序即使在进行中的拖动过程中也能运行,可以使用 Blockly.browserEvents.bind 函数。

处理中

如果您在该字段的 bindEvents_ 函数内注册了任何自定义事件监听器,则需要在 dispose 函数中取消注册这些监听器。

如果您正确初始化了字段的视图(通过将所有 DOM 元素附加到 fieldGroup_ 中),系统会自动处置字段的 DOM。

价值处理

→ 如需了解字段的值与字段文本,请参阅字段详解

验证顺序

描述验证程序运行顺序的流程图

实现类验证程序

字段应仅接受特定值。例如,数字字段应仅接受数字,颜色字段应仅接受颜色等。这是通过类和本地验证程序确保的。类验证程序遵循的规则与本地验证程序相同,只不过它也是在构造函数中运行,因此不应引用源代码块。

如需实现字段的类验证器,请替换 doClassValidation_ 函数。

doClassValidation_(newValue) {
  if (typeof newValue != 'string') {
    return null;
  }
  return newValue;
};

处理有效值

如果传递给具有 setValue 的字段的值无效,则您将收到 doValueUpdate_ 回调。默认情况下,doValueUpdate_ 函数:

  • value_ 属性设置为 newValue
  • isDirty_ 属性设置为 true

如果您只需要存储该值,并且不想进行任何自定义处理,则无需替换 doValueUpdate_

或者,如果您想执行如下操作:

  • newValue 的自定义存储空间。
  • 根据 newValue 更改其他属性。
  • 保存当前值是否有效。

您需要替换 doValueUpdate_

doValueUpdate_(newValue) {
  super.doValueUpdate_(newValue);
  this.displayValue_ = newValue;
  this.isValueValid_ = true;
}

处理无效值

如果通过 setValue 传递给该字段的值无效,则您将收到 doValueInvalid_ 回调。默认情况下,doValueInvalid_ 函数不执行任何操作。这意味着在默认情况下,系统不会显示无效值。这也意味着不会重新渲染该字段,因为系统不会设置 isDirty_ 属性。

如果您希望显示无效值,则应替换 doValueInvalid_。在大多数情况下,您应该将 displayValue_ 属性设置为无效值,将 isDirty_ 设置为 true,并替换 render_,以便块内显示组件根据 displayValue_(而非 value_)进行更新。

doValueInvalid_(newValue) {
  this.displayValue_ = newValue;
  this.isDirty_ = true;
  this.isValueValid_ = false;
}

多部分值

当您的字段包含多部分值(例如列表、向量、对象)时,您可能希望将这些部分作为单独的值进行处理。

doClassValidation_(newValue) {
  if (FieldTurtle.PATTERNS.indexOf(newValue.pattern) == -1) {
    newValue.pattern = null;
  }

  if (FieldTurtle.HATS.indexOf(newValue.hat) == -1) {
    newValue.hat = null;
  }

  if (FieldTurtle.NAMES.indexOf(newValue.turtleName) == -1) {
    newValue.turtleName = null;
  }

  if (!newValue.pattern || !newValue.hat || !newValue.turtleName) {
    this.cachedValidatedValue_ = newValue;
    return null;
  }
  return newValue;
}

在上面的示例中,newValue 的每个属性都单独进行了验证。然后,在 doClassValidation_ 函数的末尾,如果任何单个属性无效,则该值会先缓存到 cacheValidatedValue_ 属性,然后返回 null(无效)。通过使用单独验证的属性缓存对象,doValueInvalid_ 函数只需执行 !this.cacheValidatedValue_.property 检查即可单独处理它们,而不必单独重新验证每个属性。

这种用于验证多部分值的模式也可以在本地验证器中使用,但目前无法强制执行此模式。

isDirty_

isDirty_setValue 函数以及该字段的其他部分中使用的标志,用于指示是否需要重新渲染该字段。如果字段的显示值已更改,则 isDirty_ 通常应设置为 true

文字

→ 如需了解字段文本的使用位置及其与字段的值有何不同,请参阅字段详解

如果您字段的文本与字段的值不同,应替换 getText 函数以提供正确的文本。

getText() {
  let text = this.value_.turtleName + ' wearing a ' + this.value_.hat;
  if (this.value_.hat == 'Stovepipe' || this.value_.hat == 'Propeller') {
    text += ' hat';
  }
  return text;
}

创建编辑器

如果您定义了 showEditor_ 函数,Blockly 会自动监听点击操作,并在适当的时间调用 showEditor_。您可以在编辑器中显示任何 HTML,只需将其封装在两个特殊 div(称为 DropDownDiv 和 WidgetDiv)的特殊 div(浮动在 Blockly 界面的其余部分之上)中即可。

DropDownDiv 用于提供位于连接到字段的框内的编辑器。它会自动将自身放置在字段附近,同时保持在可见边界内。角度选择器和颜色选择器就是 DropDownDiv 的不错示例。

角度选择器的图片

WidgetDiv 用于提供不在 Box 中的编辑器。数字字段使用 WidgetDiv 覆盖具有 HTML 文本输入框的字段。虽然 DropDownDiv 会为您处理定位,但 WidgetDiv 不会。您需要手动定位元素。坐标系采用相对于窗口左上角的像素坐标。文本输入编辑器就是 WidgetDiv 的一个很好的例子。

文本输入编辑器的图片

showEditor_() {
  // Create the widget HTML
  this.editor_ = this.dropdownCreate_();
  Blockly.DropDownDiv.getContentDiv().appendChild(this.editor_);

  // Set the dropdown's background colour.
  // This can be used to make it match the colour of the field.
  Blockly.DropDownDiv.setColour('white', 'silver');

  // Show it next to the field. Always pass a dispose function.
  Blockly.DropDownDiv.showPositionedByField(
      this, this.disposeWidget_.bind(this));
}

WidgetDiv 示例代码

showEditor_() {
  // Show the div. This automatically closes the dropdown if it is open.
  // Always pass a dispose function.
  Blockly.WidgetDiv.show(
    this, this.sourceBlock_.RTL, this.widgetDispose_.bind(this));

  // Create the widget HTML.
  var widget = this.createWidget_();
  Blockly.WidgetDiv.getDiv().appendChild(widget);
}

清理

DropDownDiv 和 WidgetDiv 都负责销毁 widget HTML 元素,但您需要手动处置已应用于这些元素的任何事件监听器。

widgetDispose_() {
  for (let i = this.editorListeners_.length, listener;
      listener = this.editorListeners_[i]; i--) {
    Blockly.browserEvents.unbind(listener);
    this.editorListeners_.pop();
  }
}

dispose 函数在 DropDownDivnull 上下文中调用。在 WidgetDiv 上,系统会在 WidgetDiv 的上下文中调用它。无论是哪种情况,都最好在传递 dispose 函数时使用 bind 函数,如上面的 DropDownDivWidgetDiv 示例所示。

→ 如需了解关于处理(并非特定于编辑器处理)的信息,请参阅处理

更新块显示

render_ 函数用于更新字段的块显示模式,以匹配其内部值。

常见示例包括:

  • 更改文字(下拉菜单)
  • 更改颜色(颜色)

默认值

默认的 render_ 函数将显示文本设为 getDisplayText_ 函数的结果。在为遵循最大文本长度而截断字段后,getDisplayText_ 函数会将字段的 value_ 属性转换为字符串。

如果您使用的是默认块显示,并且默认文本行为适用于您的字段,则无需替换 render_

如果默认文本行为适合您的字段,但字段的块显示具有其他静态元素,您可以调用默认的 render_ 函数,但仍需替换该函数,以更新字段的大小

如果默认文本行为不适用于您的字段,或者字段的块显示方式包含其他动态元素,您需要自定义 render_ 函数

描述如何决定是否替换 render_ 的流程图

自定义渲染

如果默认呈现行为不适用于您的字段,则您需要定义自定义呈现行为。这可能涉及从设置自定义显示文本、更改图片元素到更新背景颜色等各种操作。

所有 DOM 属性更改都是合法的,仅需注意以下两点:

  1. DOM 创建应在初始化期间进行处理,因为它更高效。
  2. 您应始终更新 size_ 属性,以匹配块显示屏的大小。
render_() {
  switch(this.value_.hat) {
    case 'Stovepipe':
      this.stovepipe_.style.display = '';
      break;
    case 'Crown':
      this.crown_.style.display = '';
      break;
    case 'Mask':
      this.mask_.style.display = '';
      break;
    case 'Propeller':
      this.propeller_.style.display = '';
      break;
    case 'Fedora':
      this.fedora_.style.display = '';
      break;
  }

  switch(this.value_.pattern) {
    case 'Dots':
      this.shellPattern_.setAttribute('fill', 'url(#polkadots)');
      break;
    case 'Stripes':
      this.shellPattern_.setAttribute('fill', 'url(#stripes)');
      break;
    case 'Hexagons':
      this.shellPattern_.setAttribute('fill', 'url(#hexagons)');
      break;
  }

  this.textContent_.nodeValue = this.value_.turtleName;

  this.updateSize_();
}

正在更新大小

更新字段的 size_ 属性非常重要,因为它会告知块呈现代码如何定位字段。确切了解 size_ 应该是什么的最佳方式是进行实验。

updateSize_() {
  const bbox = this.movableGroup_.getBBox();
  let width = bbox.width;
  let height = bbox.height;
  if (this.borderRect_) {
    width += this.constants_.FIELD_BORDER_RECT_X_PADDING * 2;
    height += this.constants_.FIELD_BORDER_RECT_X_PADDING * 2;
    this.borderRect_.setAttribute('width', width);
    this.borderRect_.setAttribute('height', height);
  }
  // Note how both the width and the height can be dynamic.
  this.size_.width = width;
  this.size_.height = height;
}

采用相同的砌块颜色

如果您希望字段的元素与其附加到的块的颜色相匹配,应替换 applyColour 方法。您需要通过代码块的样式属性来获取该颜色。

applyColour() {
  const sourceBlock = this.sourceBlock_;
  if (sourceBlock.isShadow()) {
    this.arrow_.style.fill = sourceBlock.style.colourSecondary;
  } else {
    this.arrow_.style.fill = sourceBlock.style.colourPrimary;
  }
}

正在更新可修改性

updateEditable 函数可用于根据字段是否可修改来更改字段的显示方式。默认函数可让背景在不可修改/不可修改时具有/没有悬停响应(边框)。on-块显示不应根据其可编辑性而改变大小,但允许所有其他更改。

updateEditable() {
  if (!this.fieldGroup_) {
    // Not initialized yet.
    return;
  }
  super.updateEditable();

  const group = this.getClickTarget_();
  if (!this.isCurrentlyEditable()) {
    group.style.cursor = 'not-allowed';
  } else {
    group.style.cursor = this.CURSOR;
  }
}

序列化

序列化是指保存字段的状态,以便稍后可以将其重新加载到工作区。

工作区的状态始终包含相应字段的值,但也可能包含其他状态,例如字段界面的状态。例如,如果您的字段是允许用户选择国家/地区的可缩放地图,那么您还可以将缩放级别序列化。

如果您的字段可序列化,则必须将 SERIALIZABLE 属性设置为 true

Blockly 为字段提供两组序列化钩子。一对钩子与新的 JSON 序列化系统配合使用,而另一对钩子则与旧的 XML 序列化系统配合使用。

saveStateloadState

saveStateloadState 是与新的 JSON 序列化系统配合使用的序列化钩子。

在某些情况下,您不需要提供这些,因为默认实现即可。如果 (1) 您的字段是 Blockly.Field 基类的直接子类,(2) 您的值是 JSON 可序列化类型,并且 (3) 您只需要将该值序列化,则默认实现即可正常运行!

否则,您的 saveState 函数应返回表示字段状态的 JSON 可序列化对象/值。您的 loadState 函数应接受相同的 JSON 可序列化对象/值,并将其应用于该字段。

saveState() {
  return {
    'country': this.getValue(),  // Value state
    'zoom': this.getZoomLevel(), // UI state
  };
}

loadState(state) {
  this.setValue(state['country']);
  this.setZoomLevel(state['zoom']);
}

完全序列化和后备数据

saveState 还会接收可选参数 doFullSerialization。通常引用由其他序列化器(如后备数据模型)序列化的状态的字段会用到它。该参数会指示在对块进行反序列化时引用的状态将不可用,因此该字段应自行执行所有序列化操作。例如,当单个块序列化或复制粘贴块时,结果为 true。

两种常见用例是:

  • 当单个块加载到不存在后备数据模型的工作区时,该字段自身的状态具有足够的信息来创建新的数据模型。
  • 复制粘贴块时,该字段始终会创建新的后备数据模型,而不是引用现有数据模型。

使用此字段的一个字段是内置变量字段。通常,它会序列化所引用的变量的 ID,但如果 doFullSerialization 为 true,则会序列化其所有状态。

saveState(doFullSerialization) {
  const state = {'id': this.variable_.getId()};
  if (doFullSerialization) {
    state['name'] = this.variable_.name;
    state['type'] = this.variable_.type;
  }
  return state;
}

loadState(state) {
  const variable = Blockly.Variables.getOrCreateVariablePackage(
      this.getSourceBlock().workspace,
      state['id'],
      state['name'],   // May not exist.
      state['type']);  // May not exist.
  this.setValue(variable.getId());
}

变量字段执行此操作是为了确保在将其加载到不存在其变量的工作区时,它可以创建一个引用的新变量。

toXmlfromXml

toXmlfromXml 是与旧的 XML 序列化系统一起使用的序列化钩子。仅在必要时使用这些钩子(例如,您处理的是尚未迁移的旧代码库),否则请使用 saveStateloadState

您的 toXml 函数应返回一个表示字段状态的 XML 节点。您的 fromXml 函数应接受相同的 XML 节点并将其应用于该字段。

toXml(fieldElement) {
  fieldElement.textContent = this.getValue();
  fieldElement.setAttribute('zoom', this.getZoomLevel());
  return fieldElement;
}

fromXml(fieldElement) {
  this.setValue(fieldElement.textContent);
  this.setZoomLevel(fieldElement.getAttribute('zoom'));
}

可修改和可序列化的属性

EDITABLE 属性确定字段是否应具有指示其可交互的界面。默认值为 true

SERIALIZABLE 属性用于确定是否应序列化字段。默认值为 false。如果此属性为 true,您可能需要提供序列化和反序列化函数(请参阅序列化)。

自定义光标

CURSOR 属性决定了用户将鼠标悬停在字段上时会看到的光标。它应该是有效的 CSS 游标字符串。这默认为由 .blocklyDraggable 定义的游标,即抓取光标。