dart:js_interop library
Interoperability with JavaScript and browser APIs.
The JSObject type hierarchy is modeled after the JavaScript type hierarchy, and facilitates sound interoperability with JavaScript.
Note
The types defined in this library only provide static guarantees.
The runtime types differ based on the backend, so it is important to rely
on static functionality like the conversion functions, for example toJS
and not runtime mechanisms like type checks (is
) and casts (as
).
Classes
Extension Types
- JSAny
- The overall top type in the JS types hierarchy.
- JSArray
- The type of all JS arrays.
- JSArrayBuffer
-
The JavaScript
ArrayBuffer
. - JSBigInt
-
The JavaScript
BigInt
. - JSBoolean
- The Javascript booleans.
- JSBoxedDartObject
- A boxed Dart object that can be passed to JavaScript safely.
- JSDataView
-
The JavaScript
DataView
. - JSExportedDartFunction
- A JavaScript callable function created from a Dart function.
- JSFloat32Array
-
The JavaScript
Float32Array
. - JSFloat64Array
-
The Javascript
Float64Array
. - JSFunction
- The type of all JS functions.
- JSInt16Array
-
The JavaScript
Int16Array
. - JSInt32Array
-
The JavaScript
Int32Array
. - JSInt8Array
-
The JavaScript
Int8Array
. - JSNumber
- The JavaScript numbers.
- JSObject
- The representation type of all JavaScript objects for extension types.
- JSPromise
-
A JavaScript
Promise
or a promise-like object. - JSString
- The JavaScript strings.
- JSSymbol
-
The JavaScript
Symbol
s. - JSTypedArray
- The abstract supertype of all JS typed arrays.
- JSUint16Array
-
The Javascript
Uint16Array
. - JSUint32Array
-
The Javascript
Uint32Array
. - JSUint8Array
-
The JavaScript
Uint8Array
. - JSUint8ClampedArray
-
The Javascript
Uint8ClampedArray
.
Extensions
- BoolToJSBoolean
- Conversion from bool to JSBoolean.
- ByteBufferToJSArrayBuffer
- Conversion from ByteBuffer to JSArrayBuffer.
- ByteDataToJSDataView
- Conversion from ByteData to JSDataView.
- DoubleToJSNumber
- Conversion from double to JSNumber.
- Float32ListToJSFloat32Array
- Conversion from Float32List to JSFloat32Array.
- Float64ListToJSFloat64Array
- Conversion from Float64List to JSFloat64Array.
- FunctionToJSExportedDartFunction
- Conversion from Function to JSExportedDartFunction.
- FutureOfJSAnyToJSPromise
- FutureOfVoidToJSPromise
- Conversion from Future to JSPromise.
- Int16ListToJSInt16Array
- Conversion from Int16List to JSInt16Array.
- Int32ListToJSInt32Array
- Conversion from Int32List to JSInt32Array.
- Int8ListToJSInt8Array
- Conversion from Int8List to JSInt8Array.
- JSAnyOperatorExtension
- JSAnyUtilityExtension
- Common utility functions that are useful for any JS value.
- JSArrayBufferToByteBuffer
- Conversion from JSArrayBuffer to ByteBuffer.
- JSArrayToList
- Conversion from JSArray to List.
- JSBooleanToBool
- Conversion from JSBoolean to bool.
- JSBoxedDartObjectToObject
- Conversion from JSBoxedDartObject to Object.
- JSDataViewToByteData
- Conversion from JSDataView to ByteData.
- JSExportedDartFunctionToFunction
- Conversion from JSExportedDartFunction to Function.
- JSFloat32ArrayToFloat32List
- Conversion from JSFloat32Array to Float32List.
- JSFloat64ArrayToFloat64List
- Conversion from JSFloat64Array to Float64List.
- JSFunctionUtilExtension
- Utility extensions for JSFunction.
- JSInt16ArrayToInt16List
- Conversion from JSInt16Array to Int16List.
- JSInt32ArrayToInt32List
- Conversion from JSInt32Array to Int32List.
- JSInt8ArrayToInt8List
- Conversion from JSInt8Array to Int8List.
- JSNumberToNumber
- Conversion from JSNumber to double or int.
- JSPromiseToFuture
- Conversion from JSPromise to Future.
- JSStringToString
- Conversion from JSString to String.
- JSUint16ArrayToInt16List
- Conversion from JSUint16Array to Uint16List.
- JSUint32ArrayToUint32List
- Conversion from JSUint32Array to Uint32List.
- JSUint8ArrayToUint8List
- Conversion from JSUint8Array to Uint8List.
- JSUint8ClampedArrayToUint8ClampedList
- Conversion from JSUint8ClampedArray to Uint8ClampedList.
- ListToJSArray
- Conversion from List to JSArray.
- NullableObjectUtilExtension
- Utility extensions for Object?.
- NullableUndefineableJSAnyExtension
-
JS
undefined
and JSnull
are internalized differently based on the backends. In the JS backends, Dartnull
can actually be JSundefined
or JSnull
. In dart2wasm, that's not the case: there's only one Wasm valuenull
can be. Therefore, when we get back JSnull
or JSundefined
, we internalize both as Dartnull
in dart2wasm, and when we pass Dartnull
to an interop API, we pass JSnull
. In the JS backends, Dartnull
retains its original value when passed back to an interop API. Be wary of writing code where this distinction betweennull
andundefined
matters. - NumToJSExtension
- Conversion from num to JSNumber.
- ObjectToJSBoxedDartObject
- StringToJSString
- Conversion from String to JSString.
- Uint16ListToJSInt16Array
- Conversion from Uint16List to JSUint16Array.
- Uint32ListToJSUint32Array
- Conversion from Uint32List to JSUint32Array.
- Uint8ClampedListToJSUint8ClampedArray
- Conversion from Uint8ClampedList to JSUint8ClampedArray.
- Uint8ListToJSUint8Array
- Conversion from Uint8List to JSUint8Array.
Constants
- anonymous → const _Anonymous
-
An annotation that indicates a
JS
annotated class is structural and does not have a known JavaScript prototype. - staticInterop → const _StaticInterop
-
staticInterop enables the
JS
annotated class to be treated as a "static" interop class.
Properties
- globalContext → JSObject
-
A getter to retrieve the global context that is used in static interop
lowering.
no setter
Functions
-
createJSInteropWrapper<
T extends Object> (T dartObject) → JSObject -
Given a Dart object that is marked "exportable", creates a JS object that
wraps the given Dart object. Look at the
@JSExport
annotation to determine what constitutes "exportable" for a Dart class. The object literal will be a map of export names (which are either the written instance member names or their rename) to their respective Dart instance members. -
importModule(
String moduleName) → JSPromise< JSObject> -
Call to dynamically import a JS module with the given
moduleName
using the JSimport()
syntax.
Typedefs
- JSVoid = void
-
The type of
JSUndefined
when returned from functions. Unlike pure JS, no actual object will be returned.
Exceptions / Errors
- NullRejectionException
-
Exception for when the promise is rejected with a
null
orundefined
value.