ブロックライブラリを公開する

ブロック定義のライブラリを提供するプラグインは、再利用可能なブロックを Blockly コミュニティと共有するのに最適な方法です。そこで、ブロックライブラリの汎用性を可能な限り高め、有用なものにするために、このガイドラインを作成しました。

ガイドライン

ユーザーがすべてのブロックを簡単にインストールできるようにし、ユーザーが選択した特定のブロックまたはブロックの一部のみをインストールできるようにします。
- すべてを簡単にインストールできるようにする: 単一のブロック定義に必要なすべての要素（ミュータタ、拡張機能、ミックスイン、フィールドなど）をインストールする関数を指定します。プラグインで提供されるすべてのブロックを一度にインストールする関数を指定することもできます。
- 特定の部分を選択できるようにする: ブロック定義のすべての部分を個別にエクスポートし、ユーザーが独自の類似カスタムブロックを作成するために必要な部分のみをインポートできるようにする必要があります。
プラグインで副作用を使用しないでください。
- プラグインの読み込みの副作用として、ブロック、フィールド、拡張機能、その他の部分をインストールしないでください。ユーザーは、インストールするアイテムとそのタイミングを管理する必要があります。これにより、ユーザーはインストールされない部分を気にせずに、必要な部分をインポートできます。
新しいフィールドを直接インスタンス化するのではなく、JSON フィールドレジストリを使用します。
- 非推奨 - 新しいフィールドを直接インスタンス化する:
```
  const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(new Blockly.FieldNumber(123), 'NAME');
    }
  }
```
- 推奨 - JSON フィールドレジストリ:
```
  export const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(Blockly.fieldRegistry.fromJson({
              name: 'field_number',
              value: 123,
            }), 'NAME');
    }
  }
```
- フィールドレジストリを使用すると、ブロック定義を変更しなくても、ブロックで使用されているフィールドの実装を簡単に置き換えることができます。
ユーザーがすでにインストールしている内容について、前提を置かないでください。
- プラグインでカスタムフィールドや他のプラグインが必要な場合は、提供された install 関数にこれらのフィールドを自分で登録します。
- まもなく、Blockly に、すでに登録されているアイテムをエラーなく登録できるツールが提供される予定です。それまでは、拡張機能、ミュータタ、ミックスイン、フィールドを自分で登録する前に、すでに登録されているものを確認することをおすすめします。
- プラグインまたはブロック定義に必要な前提条件や依存関係を明確にします。
指定する各ブロックにジェネレータ関数を指定することを検討してください。
- すぐに使用できるジェネレータ関数を提供すると、ユーザーはブロックの構造や設計を理解しなくても、ブロックを簡単に使用できます。独自のジェネレータ関数を作成する必要がある場合は、ユーザーごとに冗長な作業が行われる可能性があります。
- JavaScript は Blockly で最もよく使用される言語であるため、提供する言語を 1 つだけ選択する場合は、Python ライブラリの実装など、特定の言語用にブロックが構築されていない限り、JavaScript を選択することをおすすめします。
- ジェネレータ関数を実装できない言語については、サポートが必要と思われる問題を投稿することを検討し、ユーザーから投稿があった場合は、それらに対する pull リクエストを受け入れます。
- ブロックにインストール関数を指定する場合は、省略可能な generators パラメータを指定できます。ユーザーがサポートしているジェネレータインスタンスを渡した場合、ブロックコードジェネレータ関数を自動的にインストールし、予約語の追加などの関連作業を行うことができます。
```
  // Your plugin's install function
  export const installMyCustomBlock(generators = {}) {
    Blockly.defineBlocks({my_custom_block: myCustomBlock});
    if (generators.javascript) {
      generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
      generators.javascript.addReservedWords('specialReservedWord');
    }
  }

  // How a user may install your block
  import {javascriptGenerator} from 'blockly/javascript';
  import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
  // installs the block definition and the javascript block-code generator
  installMyCustomBlock({javascript: javascriptGenerator});
```

フィードバック

プラグインでこれらのガイドラインに従う最適な方法について質問がある場合は、フォーラムでお知らせください。ブロックライブラリをお送りいただければ、フィードバックをお送りします。

なお、現在のところ、ブロック定義を提供するファーストパーティ製プラグインはすべて、これらのガイドラインに準拠しているわけではありません。ただし、新しいプラグインは準拠しており、既存のプラグインも移行する予定です。

ブロック ライブラリを公開する

ガイドライン

フィードバック

ブロックライブラリを公開する