このページは Cloud Translation API によって翻訳されました。

カスタムフィールドのアップグレード

2019 年 7 月（リリース 2.20190722）で、より体系化されたフィールド API が追加されました。可能な限り下位互換性を持たせることが意図されています。つまり、2019 年 7 月より前に作成したカスタムフィールドは、引き続き機能する可能性が高いということです。カスタムフィールドをアップグレードする必要があるかどうかを判断する前に、危険領域のセクションを読んで、フィールドを十分にテストしてください。

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

setText 関数は、Blockly コアによって呼び出されなくなったため、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）。
フィールド 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.

上記の警告は、EDITABLE プロパティが true であるため、Blockly はフィールドをシリアル化する必要があると認識していることを示していますが、SERIALIZABLE プロパティを定義するまで確認できないことを意味します。これをそのままにすると、すべてが正しく機能し、フィールドはシリアル化されますが、コンソールの警告が表示されます。

size_.width

this.size_.width = 0;

置き換えると次のようになります。

this.isDirty_ = true;

以下の警告は無視できますが、size_.width プロパティの代わりに isDirty_ プロパティを設定すると解決できます。

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

上記の警告は、フィールドの再レンダリングに古い方法を使用していることを検出し、新しい方法を使用することが求められていることを意味します。

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() {
  // ...
}

入力がジェスチャーシステムを通過できるように、onMouseDown_ 関数ではなく showEditor_ 関数をオーバーライドして、マウスクリックを処理することをおすすめします。

エディタの詳細については、エディタをご覧ください。

setValue

setValue 関数は、サブクラス内の重複コードを減らすテンプレート関数になりました。setValue 関数にロジックが含まれている場合は、値の処理で説明されている値処理のパスに合わせて、リファクタリングすることを検討してください。

text_

フィールドの text_ プロパティに直接アクセスしたり、更新したりしないようにすることをおすすめします。フィールドのユーザーが読み取り可能なテキストにアクセスするには、getText 関数を使用します。フィールドの保存済み値を更新するには、setValue 関数を使用します。

フィールドの値とテキストの詳細については、フィールドの構造をご覧ください。

アップグレードに関するサポートを受ける

提供する情報

サポートを依頼する際には、具体的な質問をすることをおすすめします。

非推奨例: 「この項目はどういう問題ですか？」

また、「このフィールドのアップグレードをサポートしてください」などは推奨されません。

推奨: 「フィールドテキストが正しく更新されていません。」

また、サポートする人にリソースを提供することも必要です。これらのファイルは、他のユーザーが簡単に使用できるようにする必要があります。

非推奨の方法:

コードの画像。
コードが不完全です。

推奨:

テキスト形式でフィールドコード全体を入力します。
不正なフィールド動作の GIF の画像。
不正なフィールド動作を再現する手順
アップグレード元の Blockly のバージョン。

投稿先

アップグレードに関する質問は、Blockly デベロッパーフォーラムに投稿してください。

問題が Blockly Core の問題であると確信している場合は、Blockly GitHub に問題を報告することもできます。問題を投稿する場合は、必要な情報をすべて記入してください。

カスタム フィールドのアップグレード

危険区域

Blockly.Field.register

setText

おすすめのアップグレード

直列化可能

size_.width

init

onMouseDown_

setValue

text_

アップグレードに関するサポートを受ける

提供する情報

投稿先

カスタムフィールドのアップグレード