はじめに
このページでは、Blockly コアの関数を呼び出してプロパティにアクセスするためのベスト プラクティスについて説明します。これらの原則は、Blockly 用のプラグインを作成する場合や、Blockly をスタンドアロン アプリケーションに統合する場合に適用されます。
サブクラス化と拡張
Blockly には、次のような機能を追加するための複数のパラダイムがあります。
- サブクラス（新しいレンダラの作成など）
- ミックスイン（ブロック拡張やミューテータの追加など）
- ブロックの定義（プロシージャ ブロックの定義など）
このドキュメントでは、3 つのケースはすべてサブクラス化に相当します。
サブクラスの挿入
Blockly.inject メソッドを使用した特定のクラスを置き換えることができます。これらのサブクラスは、基本クラスを拡張するか、対応するインターフェースを実装する必要があります。
サブクラスを inject メソッドに渡すことができます。
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
または、Blockly.registry を使用してクラスを登録し、レジストリ名を使用してクラスを注入することもできます。これは、インジェクション オプションを純粋な JSON として保存する場合に便利です。
Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': 'YOUR_NAME'
}
}
次のクラスを置き換えることができます。
| 登録名 | インターフェース/基本クラス |
|---|---|
blockDragger |
Blockly.IBlockDragger |
connectionChecker |
Blockly.IConnectionChecker |
connectionPreviewer |
Blockly.IConnectionPreviewer |
flyoutsVerticalToolbox |
Blockly.IFlyout |
flyoutsHorizontalToolbox |
Blockly.IFlyout |
metricsManager |
Blockly.IMetricsManager |
renderer |
Blockly.blockRendering.Renderer |
toolbox |
Blockly.IToolbox |
インターフェースの使用について詳しくは、ドキュメントのインターフェースのセクションをご覧ください。
公開設定
TypeScript のアクセス修飾子を使用して、コアライブラリの公開設定を public、private、または protected としてマークしています。一部のプロパティには、TsDoc コメント内で @internal アノテーションを付けることができます。
すべての public プロパティと protected プロパティは、Blockly ウェブサイトの参照セクションに記載されています。また、コードを読み取って公開状況を確認することもできます。
公開
public とマークされたものはすべて公開 API の一部です。モジュール内の可視性修飾子がないプロパティは、すべてパブリックとみなされます。
Google では、正当な理由や警告なしに、公開 API を頻繁に変更しないよう努めています。例外として、あるリリースで新しい API を公開し、早期のフィードバックに応じて次のリリースで変更する場合があります。その後は、パブリック関数またはプロパティの安定版と見なすことができます。
パブリック関数はどこからでも呼び出すことができ、シグネチャが変わらない限りサブクラスでオーバーライドできます。
保護された
保護された関数とプロパティには、定義元のクラスまたはサブクラスからのみアクセスできます。
サブクラスは、型シグネチャを変更せずに、保護された関数とプロパティをオーバーライドできます。
たとえば、基本レンダラクラスを拡張するカスタム レンダラは、その保護されたプロパティにアクセスできます。
いずれの場合も、コードの残りの部分で関数またはプロパティがどのように使用されるかを理解する必要があります。
private
定義と同じファイル内のコードからのみアクセスできます。これらのプロパティに直接アクセスすると、未定義の動作が発生する可能性があります。
サブクラスで非公開の関数とプロパティをオーバーライドすることはできません。
非公開プロパティは、Blockly の公開 API の一部とはみなされないため、警告なく変更される場合があります。
Blockly の一部の関数には、モジュールからエクスポートされないため、可視性アノテーションがありません。これらの関数は基本的にローカル変数であり、定義元のモジュールの外部では使用できません。私有地と同等です。
内部
内部関数と内部プロパティはコア ライブラリ内での使用を想定しており、外部では使用しないでください。これらは TsDoc @internal アノテーションで指定されます。
内部プロパティは、Blockly の公開 API の一部とはみなされないため、警告なく変更される場合があります。
内部プロパティは、コア内のどこからでもアクセスでき、シグネチャが変更されない限り、core のサブクラスでオーバーライドできます。コアライブラリ以外からはアクセスしないでください。
廃止
@deprecated とマークされているものは使用しないでください。ほとんどの非推奨には、コンソールの警告または TSDoc に推奨コードに関する指示が記載されています。
可能な限り、非推奨の関数は、意図された削除日と呼び出すべき置換関数の推奨事項を含む警告をログに記録します。
よくある質問
使用したい関数が公開されていない場合はどうすればよいですか？
Blockly コアで機能リクエストを提出します。ユースケースの説明と、公開を希望する内容を記載してください。
Google はこの機能を使用して、公開するかどうか、または同じ情報を得る別の方法があるかどうかを話し合います。
公開が決定した場合、クリエイターまたは Blockly チームが適切な変更を行い、次の Blockly リリースで公開されます。
非公開メンバーをプラグインで使用する場合は、プラグインをベータ版としてマークし、README に情報を含めることを検討してください。
Monkeypatching についてはどうですか？
monkeypatching を読む。
Blockly API の非公開部分を使用するとパッチが予告なく機能しなくなる可能性があるため、Monkeypatching は安全ではありません。プラグインでのパッチ適用は、特に危険です。同じコードにモンキーパッチを適用する他のプラグインとの間の相互作用が十分でない可能性があるためです。このため、アプリケーションやサードパーティ プラグインではモンキーパッチを使用しないことを強くおすすめします。また、ファースト パーティ プラグインでは受け入れません。
パブリック関数をオーバーライドできますか？
サブクラス化する場合: あり。それ以外の場合はモンキーパッチです。
保護された関数をオーバーライドできますか？
サブクラス化する場合: あり。それ以外の場合はモンキーパッチです。
内部関数または非公開関数をオーバーライドできますか？
これはモンキーパッチです。
プロパティに直接アクセスできるのはどのような場合ですか？ゲッターとセッターは、どのようなときに使用すべきですか？
ゲッターまたはセッターを公開している場合は、プロパティに直接アクセスするのではなく、ゲッターまたはセッターを使用してください。プロパティが public でない場合は、必ずゲッターとセッターを使用してください。
プロパティにアノテーションがない場合はどうなりますか。
デフォルトはパブリックですが、ゲッター/セッターのペアを用意する必要がある場合は、行を 1 行削除してください。
関数にアノテーションがない場合はどうなりますか。
デフォルトでは一般公開されています。
不明な場合はどうすればよいですか？
フォーラムでご質問ください。通常 1 営業日以内にご連絡いたします。