dart:js

Low-level support for interoperating with JavaScript.

INFO

You should usually use dart:js_interop instead of this library. To learn more, check out the JS interop documentation.

This library provides access to JavaScript objects from Dart, allowing Dart code to get and set properties, and call methods of JavaScript objects and invoke JavaScript functions. The library takes care of converting between Dart and JavaScript objects where possible, or providing proxies if conversion isn't possible.

This library does not make Dart objects usable from JavaScript, their methods and properties are not accessible, though it does allow Dart functions to be passed into and called from JavaScript.

JsObject is the core type and represents a proxy of a JavaScript object. JsObject gives access to the underlying JavaScript objects properties and methods. JsObjects can be acquired by calls to JavaScript, or they can be created from proxies to JavaScript constructors.

The top-level getter context provides a JsObject that represents the global object in JavaScript, usually window.

The following example shows an alert dialog via a JavaScript call to the global function alert():

import 'dart:js';

main() => context.callMethod('alert', ['Hello from Dart!']);

This example shows how to create a JsObject from a JavaScript constructor and access its properties:

import 'dart:js';

main() {
  var object = JsObject(context['Object']);
  object['greeting'] = 'Hello';
  object['greet'] = (name) => "${object['greeting']} $name";
  var message = object.callMethod('greet', ['JavaScript']);
  context['console'].callMethod('log', [message]);
}

Proxying and automatic conversion

When setting properties on a JsObject or passing arguments to a JavaScript method or function, Dart objects are automatically converted or proxied to JavaScript objects. When accessing JavaScript properties, or when a Dart closure is invoked from JavaScript, the JavaScript objects are also converted to Dart.

Functions and closures are proxied in such a way that they are callable. A Dart closure assigned to a JavaScript property is proxied by a function in JavaScript. A JavaScript function accessed from Dart is proxied by a JsFunction, which has a JsFunction.apply method to invoke it.

The following types are transferred directly and not proxied:

• Basic types: null, bool, num, String, DateTime
• TypedData, including its subclasses like Int32List, but notByteBuffer
• When compiling for the web, also: Blob, Event, ImageData, KeyRange, Node, and Window.

Converting collections with JsObject.jsify()

To create a JavaScript collection from a Dart collection use the JsObject.jsify constructor, which converts Dart Maps and Iterables into JavaScript Objects and Arrays.

The following expression creates a new JavaScript object with the properties a and b defined:

var jsMap = JsObject.jsify({'a': 1, 'b': 2});

This expression creates a JavaScript array:

var jsArray = JsObject.jsify([1, 2, 3]);

Classes

Class	Description
JsArray<E>	A List that proxies a JavaScript array.
JsFunction	A proxy on a JavaScript Function object.
JsObject	A proxy on a JavaScript object.

Functions

Function	Description
allowInterop<F extends Function>	Returns a wrapper around function f that can be called from JavaScript using package:js JavaScript interop.
allowInteropCaptureThis	Returns a wrapper around function f that can be called from JavaScript using package:js JavaScript interop, passing JavaScript this as the first argument.

Properties

Property	Description
context	The JavaScript global object, usually window.