過去の JS 相互運用

このページでは、Dart 3.7 以降非推奨となっている、過去の JS 相互運用のバージョンについて説明します。そのため、今後 dart:js_interop を使用することを推奨しており、古い相互運用ライブラリの使用は可能な限り移行してください。dart:html やその他の Web ライブラリは密接に関連していますが、これらは package:web のページで扱われています。

dart:js は、JS オブジェクトと相互運用するために具体的な オブジェクトラッパー を公開していました。このラッパーは、ラップされた JS オブジェクトのプロパティを動的に取得、設定、呼び出すための文字列ベースのメソッドを含んでいました。ラッパーのコストによりパフォーマンスが低下し、使用する上でもより困難でした。例えば、相互運用メンバーを宣言できなかったため、文字列に頼る必要があり、コード補完が利用できませんでした。dart:js で公開されていた allowInterop のような機能の多くは、後に他の相互運用ライブラリを通じて再公開されました。

このライブラリは、package:js と dart:js_util がリリースされて以来、レガシーとなっています。

package:js は、相互運用型とメンバーを宣言する機能を提供しました。これにより、ユーザーは相互運用拡張型ではなく、相互運用クラスを記述できるようになりました。実行時には、これらのクラスは dart:js_interop の JSObject に似た型に消去されました。

@JS()
class JSType {}

package:js のユーザーは、dart:js_interop の構文とセマンティクスに慣れ親しむでしょう。クラス定義を拡張型に置き換えることで dart:js_interop に移行できる場合があり、多くのケースで機能するはずです。

ただし、重要な違いがあります。

• package:js の型は、ブラウザ API と相互運用するためには使用できませんでした。dart:js_interop の型は使用できます。
• package:js は動的ディスパッチを許可していました。これは、package:js の型を dynamic にキャストして、そこに相互運用メンバーを呼び出した場合、正しいメンバーに転送されることを意味しました。dart:js_interop では、これはもはや不可能です。
• package:js の @JS には、external メンバーの戻り値の型がチェックされなかったため、健全性の保証がありませんでした。dart:js_interop は健全です。
• package:js の型では、インスタンスメンバーの名前を変更したり、非external メンバーを持ったりすることはできませんでした。
• package:js の型は、非相互運用クラスのサブタイプになったり、スーパータイプになったりすることができました。これは、モックのためにしばしば使用されていました。dart:js_interop では、モックは JS オブジェクトを置き換えることによって行われます。モックに関する チュートリアル を参照してください。
• @anonymous 型は、オブジェクトリテラルのコンストラクタを持つ相互運用型を宣言する方法でした。dart:js_interop では、型をこのように区別せず、任意の external 名前付き引数コンストラクタがオブジェクトリテラルコンストラクタとなります。

@JS および @anonymous とともに、package:js は後に @staticInterop を公開しました。これは、相互運用拡張型のプロトタイプでした。これは、拡張型が利用可能になるまでの過渡的な構文として意図されており、dart:js_interop と同様に表現力があり、制限的でした。

@staticInterop 型は、暗黙的に JSObject に消去されました。ユーザーは、静的セマンティクスのみが使用できるように、すべてのインスタンスメンバーを拡張機能で宣言する必要があり、より強力な健全性保証がありました。ユーザーはこれを使用してブラウザ API と対話することができ、名前の変更や非external メンバーのようなものも許可されていました。相互運用拡張型と同様に、動的ディスパッチのサポートはありませんでした。

@staticInterop クラスは、クラスを拡張型に変更し、アノテーションを削除するだけで、ほとんどの場合、相互運用拡張型に移行できます。

dart:js_interop は、言語に拡張型が追加されるまで静的相互運用セマンティクスをサポートするために @staticInterop (および @anonymous、ただし @staticInterop が使用されている場合のみ) を公開しました。そのような型はすべて、拡張型に移行する必要があります。

dart:js_util は、package:js 型で宣言できなかった、または値を行き来させるために必要だった多くのユーティリティ関数を提供しました。これには、次のようなメンバーが含まれていました。

• allowInterop (現在は Function.toJS)
• getProperty/setProperty/callMethod/callConstructor (現在は dart:js_interop_unsafe)
• さまざまな JS 演算子
• 型チェックヘルパー
• モックサポート
• その他。

dart:js_interop および dart:js_interop_unsafe には、現在これらのヘルパーが、おそらく代替構文で含まれています。