このページでは、コア Blockly で関数を呼び出してプロパティにアクセスするためのベスト プラクティスについて説明します。これらの原則は、Blockly のプラグインの作成と、Blockly をスタンドアロン アプリケーションに統合する場合に適用されます。
公開設定
TypeScript アクセス修飾子を使用して、コアライブラリの公開設定を public、private、protected としてマークします。一部のプロパティは、TsDoc コメントで @internal でアノテーションされている場合があります。
public プロパティと protected プロパティはすべて、Blockly ウェブサイトのリファレンス セクションに記載されています。コードを読み取ることで公開設定を確認することもできます。
公開
public とマークされているものは、公開 API の一部です。可視性修飾子がないモジュール内のプロパティは、公開と見なされます。
Google は、パブリック API を頻繁に変更したり、正当な理由と警告なしに変更したりしないよう努めています。例外: 新しい API を 1 つのリリースで公開し、早期のフィードバックに応じて次のリリースで変更する場合があります。その後、パブリック関数またはプロパティを安定していると見なすことができます。
パブリック関数はどこからでも呼び出すことができ、シグネチャが変更されない限り、サブクラスでオーバーライドできます。
保護
保護された関数とプロパティには、定義クラスまたはサブクラスからのみアクセスできます。
サブクラスは、型シグネチャを変更せずに、保護された関数とプロパティをオーバーライドできます。
たとえば、ベース レンダラクラスを拡張するカスタム レンダラは、その保護されたプロパティにアクセスできます。
いずれの場合も、関数またはプロパティが残りのコードでどのように使用されているかを理解する必要があります。
非公開
これらの変数にアクセスできるのは、定義と同じファイル内のコードのみです。これらのプロパティに直接アクセスすると、未定義の動作が発生する可能性があります。
サブクラスでは、プライベート関数とプロパティをオーバーライドすることはできません。
非公開プロパティは Blockly の公開 API の一部と見なされないため、事前通知なく変更される可能性があります。
Blockly の一部の関数には、モジュールからエクスポートされていないため、公開設定のアノテーションがありません。これらの関数は基本的にローカル変数であり、定義モジュールの外部では使用できません。これらは、非公開プロパティと同等と見なされます。
内部
内部関数と内部プロパティは、コア ライブラリ内で使用することを想定しており、外部では使用しないでください。これらは TsDoc @internal アノテーションで指定されます。
内部プロパティは Blockly の公開 API の一部と見なされないため、予告なく変更される可能性があります。
内部プロパティには、コア内の任意の場所からアクセスできます。また、署名が変更されない限り、コアのサブクラスでオーバーライドできます。コア ライブラリの外部からアクセスすることはできません。
廃止
@deprecated とマークされているものは使用しないでください。ほとんどの非推奨には、コンソール ワーニングまたは TSDoc に、推奨されるコードに関する指示が含まれています。
可能であれば、非推奨の関数は、削除予定日と、呼び出す代替関数の推奨事項を含む警告をログに記録します。
よくある質問
Blockly チームがよく受けた質問を以下に示します。
使用する関数が公開されていない場合はどうすればよいですか？
コア Blockly に関する機能リクエストを提出します。ユースケースの説明と、公開する内容の説明を記載してください。
この機能を使用して、情報を公開するかどうか、または同じ情報を入手する他の方法があるかどうかについて、話し合うようリクエストします。
公開することに決定した場合は、ユーザーまたは Blockly チームが適切な変更を行い、次の Blockly リリースで公開されます。
プラグインで非公開のメンバーを使用する場合は、プラグインをベータ版としてマークし、README に情報を含めることを検討してください。
モンキー パッチはどうですか？
モンキー パッチについて確認する。
モンキー パッチは安全ではありません。Blockly API の非公開部分を使用しているため、パッチが予告なく機能しなくなる可能性があります。プラグインにパッチを適用するのは特に危険です。同じコードにモンキーパッチを適用する他のプラグインとコードがうまく連携しない可能性があります。そのため、アプリやサードパーティ プラグインでのモンキー パッチは強くおすすめしません。また、ファーストパーティ プラグインでは許可されません。
公開関数をオーバーライドできますか？
サブクラス化する場合: はい。それ以外の場合: いいえ。これはモンキー パッチです。
プロテクト関数をオーバーライドできますか？
サブクラス化する場合: はい。それ以外の場合: いいえ。これはモンキー パッチです。
内部関数や非公開関数をオーバーライドできますか？
いいえ、それはモンキー パッチです。
プロパティに直接アクセスできるようになるのはいつですか？ゲッターとセッターはどのような場合に使用すればよいですか？
ゲッターまたはセッターが公開されている場合は、プロパティに直接アクセスするのではなく、それを使用してください。プロパティが公開されていない場合は、必ずゲッターとセッターを使用してください。
プロパティにアノテーションがない場合
デフォルトでは公開されていますが、ゲッター/セッター ペアを設定したい場合は、お知らせください。
関数にアノテーションがない場合
デフォルトでは公開設定になっています。
それでも不明な場合はどうすればよいですか？
フォーラムで質問すると、数日以内に回答いたします。