カスタム プロシージャ ブロックを作成する

カスタム プロシージャ ブロックを作成するには、次のことを行う必要があります。

1. 手順の使用に関するページの説明に従って、@blockly/block-shareable-procedures プラグインをインストールします。
2. 概要ページで説明されているように、JSON シリアル化システムを使用します。

ワークスペースにデータモデルを追加する

プロシージャ定義とプロシージャ呼び出し元ブロックはどちらも、プロシージャのシグネチャ（名前、パラメータ、戻り値）を定義するバッキング データモデルを参照します。これにより、アプリケーションをより柔軟に設計できます（あるワークスペースでプロシージャを定義して、別のワークスペースで参照するなど）。

つまり、ブロックを機能させるには、プロシージャのデータモデルをワークスペースに追加する必要があります。これにはさまざまな方法があります（カスタム UI など）。

@blockly/block-shareable-procedures は、ワークスペースにインスタンス化される際にプロシージャ定義ブロックによってバッキング データモデルを動的に作成することで、これを行います。これを自身で実装するには、init でモデルを作成し、destroy で削除します。

import {ObservableProcedureModel} from '@blockly/block-shareable-procedures';

Blockly.Blocks['my_procedure_def'] = {
  init: function() {
    this.model = new ObservableProcedureModel('default name');
    this.workspace.getProcedureMap().add(model);
    // etc...
  }

  destroy: function() {
    // (Optionally) Destroy the model when the definition block is deleted.

    // Insertion markers reference the model of the original block.
    if (this.isInsertionMarker()) return;
    this.workpace.getProcedureMap().delete(model.getId());
  }
}

ブロックに関する情報を返す

プロシージャ定義とプロシージャ コール ブロックには、getProcedureModel、isProcedureDef、getVarModels の各メソッドを実装する必要があります。これは、Blockly コードがプロシージャ ブロックに関する情報を取得するために使用するフックです。

Blockly.Blocks['my_procedure_def'] = {
  getProcedureModel() {
    return this.model;
  },

  isProcedureDef() {
    return true;
  },

  getVarModels() {
    // If your procedure references variables
    // then you should return those models here.
    return [];
  },
};

Blockly.Blocks['my_procedure_call'] = {
  getProcedureModel() {
    return this.model;
  },

  isProcedureDef() {
    return false;
  },

  getVarModels() {
    // If your procedure references variables
    // then you should return those models here.
    return [];
  },
};

更新時に再レンダリングをトリガーする

プロシージャ定義とプロシージャ コール ブロックには、doProcedureUpdate メソッドを実装する必要があります。これは、データモデルが呼び出すフックで、プロシージャ ブロックに再レンダリングを指示します。

Blockly.Blocks['my_procedure_def'] = {
  doProcedureUpdate() {
    this.setFieldValue('NAME', this.model.getName());
    this.setFieldValue(
        'PARAMS',
        this.model.getParameters()
            .map((p) => p.getName())
            .join(','));
    this.setFieldValue(
        'RETURN', this.model.getReturnTypes().join(',');
  }
};

Blockly.Blocks['my_procedure_call'] = {
  doProcedureUpdate() {
    // Similar to the def block above...
  }
};

カスタムのシリアル化を追加する

プロシージャ ブロックのシリアル化では、2 つの処理を行う必要があります。

1. JSON から読み込む場合、ブロックとモデルは個別にシリアル化されているため、ブロックはバッキング データモデルへの参照を取得する必要があります。
2. プロシージャ ブロックをコピーして貼り付ける場合は、ブロックでプロシージャ モデルの状態全体をシリアル化して、複製できるようにする必要があります。

どちらも saveExtraState と loadExtraState を通じて処理されます。カスタム プロシージャ ブロックは、JSON シリアル化システムを使用する場合にのみサポートされるため、ここで定義する必要があるのは JSON シリアル化フックだけです。

import {
    ObservableProcedureModel,
    ObservableParameterModel,
    isProcedureBlock
} from '@blockly/block-shareable-procedures';

Blockly.Blocks['my_procedure_def'] = {
  // When doFullSerialization is true, we should serialize the full state of
  // the model.
  saveExtraState(doFullSerialization) {
    const state = Object.create(null);
    state['procedureId']: this.model.getId();

    if (doFullSerialization) {
      state['name'] = this.model.getName();
      state['parameters'] = this.model.getParameters().map((p) => {
        return {name: p.getName(), p.getId()};
      });
      state['returnTypes'] = this.model.getReturnTypes();

      // Flag for deserialization.
      state['createNewModel'] = true;
    }

    return state;
  },

  loadExtraState(state) {
    const id = state['procedureId']
    const map = this.workspace.getProcedureMap();

    if (map.has(id) && !state['createNewModel']) {
      // Delete the existing model (created in init).
      map.delete(this.model.getId());
      // Grab a reference to the model we're supposed to reference.
      this.model = map.get(id);
      this.doProcedureUpdate();
      return;
    }

    // There is no existing procedure model (we are likely pasting), so
    // generate it from JSON.
    this.model
        .setName(state['name'])
        .setReturnTypes(state['returnTypes']);
    for (const [i, param] of state['parameters'].entries()) {
      this.model.insertParameter(
          i,
          new ObservableParameterModel(
              this.workspace, param['name'], param['id']));
    }
    this.doProcedureUpdate();
  },
};

Blockly.Blocks['my_procedure_call'] = {
  saveExtraState() {
    return {
      'procedureId': this.model.getId(),
    };
  },

  loadExtraState(state) {
    // Delete our existing model (created in init).
    this.workspace.getProcedureMap().delete(model.getId());
    // Grab a reference to the new model.
    this.model = this.workspace.getProcedureMap()
        .get(state['procedureId']);
    if (this.model) this.doProcedureUpdate();
  },

  // Handle pasting after the procedure definition has been deleted.
  onchange(event) {
    if (event.type === Blockly.Events.BLOCK_CREATE &&
        event.blockId === this.id) {
      if(!this.model) { // Our procedure definition doesn't exist =(
        this.dispose();
      }
    }
  }
};

必要に応じて処置モデルを変更する

ユーザーが処置モデルを変更する機能を追加することもできます。insertParameter、deleteParameter、または setReturnTypes のメソッドを呼び出すと、（doProcedureUpdate を介して）ブロックの再レンダリングが自動的にトリガーされます。

プロシージャ モデルを変更する UI の作成オプションには、ミューテータ（組み込みプロシージャ ブロックで使用）、クリック ハンドラを含むイメージ フィールド、Blockly の完全に外部のものなどを使用できます。

ツールボックスにブロックを追加する

Blockly の組み込み動的プロシージャ カテゴリは、Blockly の組み込みプロシージャ ブロックに固有のものです。そのため、ブロックにアクセスするには、独自のカスタム動的カテゴリを定義して、ツールボックスに追加する必要があります。

const proceduresFlyoutCallback = function(workspace) {
  const blockList = [];
  blockList.push({
    'kind': 'block',
    'type': 'my_procedure_def',
  });
  for (const model of
        workspace.getProcedureMap().getProcedures()) {
    blockList.push({
      'kind': 'block',
      'type': 'my_procedure_call',
      'extraState': {
        'procedureId': model.getId(),
      },
    });
  }
  return blockList;
};

myWorkspace.registerToolboxCategoryCallback(
    'MY_PROCEDURES', proceduresFlyoutCallback);