研究問卷調查：與我們分享您使用 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_;
}

自動處理：

檢查新值是否不同於舊值。
正在更新值。
啟動變更事件。
重新轉譯欄位。

您需要處理：

值驗證 (doClassValidation_)：
欄位文字 (getText)。
欄位 UI

，瞭解如何調查及移除這項存取權。

建議升級

建議升級的部分是 Field 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_);
};

也就是說，區塊現在會自動處理：

檢查該欄位是否已初始化。
建立 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 函式更新欄位中儲存的值。

如要進一步瞭解欄位的值與文字，請參閱欄位剖析。

取得升級協助

提供內容

尋求協助時，最好提出問題：

不建議的做法是：「這個欄位有什麼問題？」

也不建議您說：「幫我升級這個欄位」。

建議做法：「欄位文字未正確更新。」

此外，也必須向協助您的人員提供資源。這些檔案應該要能方便他人使用

不建議採用：

程式碼圖像。
程式碼不完整。

建議：

以文字格式填寫完整的欄位程式碼。
呈現不良欄位行為的 GIF 圖片。
重現問題欄位行為的步驟。
您要升級的來源區塊版本。

發布地點

張貼升級問題給區塊開發人員論壇。

如果您確定問題是區塊核心發生問題，您可以請張貼問題位於區塊式 GitHub如果您決定張貼問題，請填寫必要資訊。