ブロック定義のライブラリを提供するプラグインは、再利用可能なブロックを Blockly コミュニティと共有するのに最適です。Google では、ブロック ライブラリをできるだけ汎用的で有用なものにするために、このようなガイドラインを作成しました。
ガイドライン
- ユーザーがすべてのブロックを簡単に取り付けられるようにします。また、ユーザーが選択した特定のブロックまたはブロックの一部のみをインストールできるようにします。
- すべてを簡単にインストールできるようにする: これを行うには、1 つのブロック定義に必要なすべての要素(ミューテータ、拡張機能、ミックスイン、フィールドなど)をインストールする関数を提供します。プラグインで提供されるすべてのブロックを一度にインストールする関数を用意することもできます。
- 特定の部分を選択できるようにする: ブロック定義のすべての部分を個別にエクスポートする必要があります。これにより、ユーザーが独自の同様のカスタム ブロックを作成するために必要な部分のみをインポートできるようになります。
- プラグインで副作用を使用しないでください。
- プラグインの読み込みの副作用として、ブロック、フィールド、拡張機能、その他の要素をインストールしないでください。ユーザーは、どのものをいつインストールするかを常に制御する必要があります。これにより、ユーザーは不要なピースがインストールされることを心配することなく、必要なピースをインポートできます。
新しいフィールドを直接インスタンス化するのではなく、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
関数でそれらのフィールドを自分で登録します。 - 近日中に、登録済みのアイテムをエラーなしで登録できるツールを提供する予定です。それまでは、拡張機能、ミューテータ、ミックスイン、フィールドを自分で登録する前に、すでに登録されているものを確認してください。
- プラグインまたはブロックの定義に必要な前提条件や依存関係を明確にしておきます。
- プラグインにカスタム フィールドやその他のプラグインが必要な場合は、用意された
指定するブロックごとにジェネレータ関数を用意することを検討してください。
- すぐに使用できるジェネレータ関数が提供されるため、ユーザーはブロックの構造や設計を理解していなくても簡単にブロックを使用できます。ユーザーが独自のジェネレータ関数を作成する必要がある場合、各ユーザーによって冗長な作業が実行される可能性があります。
- JavaScript は Blockly で最も一般的に使用されている言語です。そのため、提供する言語を 1 つのみ選択する場合は、JavaScript をおすすめします。ただし、Python ライブラリの実装など、特定の言語用にブロックが作成されている場合を除きます。
- ジェネレータ関数を実装できない言語については「ヘルプ」問題を投稿し、ユーザーが貢献した場合は 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});
フィードバック
プラグインでこれらのガイドラインを遵守する方法に関してご不明な点がある場合は、フォーラムでお問い合わせください。ぜひブロック ライブラリのフィードバックをお寄せください。
ブロック定義を提供するすべてのファースト パーティ プラグインが現在このガイドラインに準拠しているわけではありませんが、新しいプラグインはこのガイドラインに従っており、既存のプラグインを移行する予定です。