JS 类型
Dart 值和 JS 值属于不同的语言域。当编译到 Wasm 时,它们也在单独的运行时中执行。因此,您应该将 JS 值视为外部类型。为了给 JS 值提供 Dart 类型,dart:js_interop
暴露了一组以 JS
为前缀的类型,称为“JS 类型”。这些类型用于在编译时区分 Dart 值和 JS 值。
重要的是,这些类型的具体化方式取决于您是编译到 Wasm 还是 JS。这意味着它们的运行时类型会不同,因此您不能使用 is
检查和 as
类型转换。为了与这些 JS 值交互和检查它们,您应该使用外部
互操作成员或转换。
类型层级结构
#JS 类型构成了一个自然的类型层级结构
- 顶层类型:
JSAny
,表示任何非空 JS 值- 基本类型:
JSNumber
、JSBoolean
、JSString
JSSymbol
JSBigInt
JSObject
,表示任何 JS 对象JSFunction
JSExportedDartFunction
,表示转换为 JS 函数的 Dart 回调
JSArray
JSPromise
JSDataView
JSTypedArray
- JS 类型化数组,例如
JSUint8Array
- JS 类型化数组,例如
JSBoxedDartObject
,允许用户在同一 Dart 运行时内封装并透明地传递 Dart 值- 从 Dart 3.4 开始,
dart:js_interop
中的类型ExternalDartReference
也允许用户透明地传递 Dart 值,但它不是 JS 类型。请此处了解更多关于每种选项的权衡。
- 从 Dart 3.4 开始,
- 基本类型:
您可以在 dart:js_interop
API 文档中找到每种类型的定义。
转换
#要在一个域中使用另一个域的值,您可能希望将该值转换为另一个域的相应类型。例如,您可能希望将 Dart 的 List<JSString>
转换为 JS 字符串数组(由 JS 类型 JSArray<JSString>
表示),以便可以将该数组传递给 JS 互操作 API。
Dart 在各种 Dart 类型和 JS 类型上提供了一些转换成员,用于在域之间转换值。
将值从 Dart 转换为 JS 的成员通常以 toJS
开头
String str = 'hello world';
JSString jsStr = str.toJS;
将值从 JS 转换为 Dart 的成员通常以 toDart
开头
JSNumber jsNum = ...;
int integer = jsNum.toDartInt;
并非所有 JS 类型都支持转换,也并非所有 Dart 类型都支持转换。通常,转换表如下所示
dart:js_interop 类型 | Dart 类型 |
---|---|
JSNumber 、JSBoolean 、JSString | num 、int 、double 、bool 、String |
JSExportedDartFunction | Function |
JSArray<T extends JSAny?> | List<T extends JSAny?> |
JSPromise<T extends JSAny?> | Future<T extends JSAny?> |
类型化数组,例如 JSUint8Array | 来自 dart:typed_data 的类型化列表 |
JSBoxedDartObject | 不透明 Dart 值 |
ExternalDartReference | 不透明 Dart 值 |
对 external
声明和 Function.toJS
的要求
#为了确保类型安全和一致性,编译器对进出 JS 的类型施加了要求。不允许将任意 Dart 值传递给 JS。相反,编译器要求用户使用兼容的互操作类型、ExternalDartReference
或原始类型,这些类型会由编译器隐式转换。例如,以下情况是被允许的
@JS()
external void primitives(String a, int b, double c, num d, bool e);
@JS()
external JSArray jsTypes(JSObject _, JSString __);
extension type InteropType(JSObject _) implements JSObject {}
@JS()
external InteropType get interopType;
@JS()
external void externalDartReference(ExternalDartReference _);
而以下情况会返回错误
@JS()
external Function get function;
@JS()
external set list(List _);
当您使用 Function.toJS
使 Dart 函数可在 JS 中调用时,也存在同样的要求。进出此回调的值必须是兼容的互操作类型或原始类型。
如果您使用像 String
这样的 Dart 原始类型,编译器会进行隐式转换,将该值从 JS 值转换为 Dart 值。如果性能至关重要,并且您不需要检查字符串的内容,那么使用 JSString
代替以避免转换成本可能是有意义的,就像第二个例子中那样。
兼容性、类型检查和类型转换
#JS 类型的运行时类型可能因编译器而异。这会影响运行时类型检查和类型转换。因此,几乎总是避免对互操作类型的值或目标类型为互操作类型的进行 is
检查
void f(JSAny a) {
if (a is String) { … }
}
void f(JSAny a) {
if (a is JSObject) { … }
}
此外,避免在 Dart 类型和互操作类型之间进行类型转换
void f(JSString s) {
s as String;
}
要对 JS 值进行类型检查,请使用检查 JS 值本身的互操作成员,例如 typeofEquals
或 instanceOfString
void f(JSAny a) {
// Here `a` is verified to be a JS function, so the cast is okay.
if (a.typeofEquals('function')) {
a as JSFunction;
}
}
从 Dart 3.4 开始,您可以使用 isA
辅助函数来检查值是否为任何互操作类型
void f(JSAny a) {
if (a.isA<JSString>()) {} // `typeofEquals('string')`
if (a.isA<JSArray>()) {} // `instanceOfString('Array')`
if (a.isA<CustomInteropType>()) {} // `instanceOfString('CustomInteropType')`
}
根据类型参数,它会将调用转换为该类型的适当类型检查。
Dart 可能会添加 Lint 规则,以便更容易避免对 JS 互操作类型进行运行时检查。请参阅问题 #4841 以获取更多详细信息。
null
与 undefined
#JS 既有 null
值,也有 undefined
值。这与只有 null
的 Dart 不同。为了使 JS 值更易于使用,如果互操作成员返回 JS 的 null
或 undefined
,编译器会将这些值映射到 Dart 的 null
。因此,以下示例中的 value
这样的成员可以解释为返回 JS 对象、JS 的 null
或 undefined
@JS()
external JSObject? get value;
如果返回类型未声明为可空,则如果返回的值是 JS 的 null
或 undefined
,程序将抛出错误以确保健全性。
JSBoxedDartObject
与 ExternalDartReference
#从 Dart 3.4 开始,JSBoxedDartObject
和 ExternalDartReference
都可以用来通过 JavaScript 传递对 Dart Object
的不透明引用。然而,JSBoxedDartObject
将不透明引用封装在一个 JavaScript 对象中,而 ExternalDartReference
本身就是引用,因此不是 JS 类型。
如果您需要 JS 类型,或者需要额外检查以确保 Dart 值不会被传递到另一个 Dart 运行时,请使用 JSBoxedDartObject
。例如,如果 Dart 对象需要放在 JSArray
中或传递给接受 JSAny
的 API,请使用 JSBoxedDartObject
。否则请使用 ExternalDartReference
,因为它会更快。
请参阅 toExternalReference
和 toDartObject
来进行与 ExternalDartReference
之间的转换。