Index: pkg/js/README.md |
diff --git a/pkg/js/README.md b/pkg/js/README.md |
index 67580adc58d6d592eba9fb06f33db2b976e5af94..af4b9314e7f07024394cffccb9ac6d15f784a1a1 100644 |
--- a/pkg/js/README.md |
+++ b/pkg/js/README.md |
@@ -1,7 +1,86 @@ |
-The package now only contains annotations specifying the shape of the |
-JavaScript API to import into Dart. |
+Methods and annotations to specify interoperability with JavaScript APIs. |
-The core implementation is defined directly in Dart2Js, Dartium, and dev_compiler. |
+*Note: This package is beta software.* |
+ |
+*Note: This packages requires Dart SDK `>=1.13.0-dev.7`.* |
+ |
+### Adding the dependency |
+ |
+Add the following to your `pubspec.yaml`: |
+ |
+```yaml |
+dependencies: |
+ js: ^0.6.0-beta |
+``` |
+ |
+#### Passing functions to JavaScript. |
+ |
+If you are passing a Dart function to a JavaScript API, you must wrap it using |
+`allowInterop` or `allowInteropCaptureThis`. |
+ |
+### Examples |
+ |
+#### Calling methods |
+ |
+```dart |
+// Calls invoke JavaScript `JSON.stringify(obj)`. |
+@Js("JSON.stringify") |
+external String stringify(obj); |
+``` |
+ |
+#### Classes and Namespaces |
+ |
+```dart |
+@Js('google.maps') |
+library maps; |
+ |
+// Invokes the JavaScript getter `google.maps.map`. |
+external Map get map; |
+ |
+// `new Map` invokes JavaScript `new google.maps.Map(location)` |
+@Js() |
+class Map { |
+ external Map(Location location); |
+ external Location getLocation(); |
+} |
+ |
+// `new Location(...)` invokes JavaScript `new google.maps.LatLng(...)` |
+// |
+// We recommend against using custom JavaScript names whenever |
+// possible. It is easier for users if the JavaScript names and Dart names |
+// are consistent. |
+@Js("LatLng") |
+class Location { |
+ external Location(num lat, num lng); |
+} |
+``` |
+ |
+#### Maps |
+ |
+Dart `Map` objects, including literals, are "opaque" in JavaScript. |
+You must create Dart classes for each of these. |
+ |
+```js |
+// JavaScript |
+printOptions({responsive: true}); |
+``` |
+ |
+```dart |
+// Dart |
+void main() { |
+ printOptions(new Options(responsive: true)); |
+} |
+ |
+@Js() |
+external printOptions(Options options); |
+ |
+@Js() |
+class Options { |
+ external bool get responsive; |
+ |
+ external factory Options({bool responsive}); |
+} |
+``` |
## Contributing and Filing Bugs |
@@ -11,5 +90,5 @@ We also love and accept community contributions, from API suggestions to pull re |
Please file an issue before beginning work so we can discuss the design and implementation. |
We are trying to create issues for all current and future work, so if something there intrigues you (or you need it!) join in on the discussion. |
-All we require is that you sign the |
+Code contributors must sign the |
[Google Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual?csw=1). |