OLD | NEW |
| (Empty) |
1 Methods and annotations to specify interoperability with JavaScript APIs. | |
2 | |
3 *This packages requires Dart SDK 1.13.0.* | |
4 | |
5 *This is beta software. Please files [issues].* | |
6 | |
7 ### Adding the dependency | |
8 | |
9 Add the following to your `pubspec.yaml`: | |
10 | |
11 ```yaml | |
12 dependencies: | |
13 js: ^0.6.0 | |
14 ``` | |
15 | |
16 ### Example | |
17 | |
18 See the [Chart.js Dart API](https://github.com/google/chartjs.dart/) for an | |
19 end-to-end example. | |
20 | |
21 ### Usage | |
22 | |
23 #### Calling methods | |
24 | |
25 ```dart | |
26 // Calls invoke JavaScript `JSON.stringify(obj)`. | |
27 @JS("JSON.stringify") | |
28 external String stringify(obj); | |
29 ``` | |
30 | |
31 #### Classes and Namespaces | |
32 | |
33 ```dart | |
34 @JS('google.maps') | |
35 library maps; | |
36 | |
37 // Invokes the JavaScript getter `google.maps.map`. | |
38 external Map get map; | |
39 | |
40 // `new Map` invokes JavaScript `new google.maps.Map(location)` | |
41 @JS() | |
42 class Map { | |
43 external Map(Location location); | |
44 external Location getLocation(); | |
45 } | |
46 | |
47 // `new Location(...)` invokes JavaScript `new google.maps.LatLng(...)` | |
48 // | |
49 // We recommend against using custom JavaScript names whenever | |
50 // possible. It is easier for users if the JavaScript names and Dart names | |
51 // are consistent. | |
52 @JS("LatLng") | |
53 class Location { | |
54 external Location(num lat, num lng); | |
55 } | |
56 ``` | |
57 | |
58 #### JavaScript object literals | |
59 | |
60 Many JavaScript APIs take an object literal as an argument. For example: | |
61 ```js | |
62 // JavaScript | |
63 printOptions({responsive: true}); | |
64 ``` | |
65 | |
66 If you want to use `printOptions` from Dart, you cannot simply pass a Dart `Map` | |
67 object – they are are "opaque" in JavaScript. | |
68 | |
69 | |
70 Instead, create a Dart class with both the `@JS()` and | |
71 `@anonymous` annotations. | |
72 | |
73 ```dart | |
74 // Dart | |
75 void main() { | |
76 printOptions(new Options(responsive: true)); | |
77 } | |
78 | |
79 @JS() | |
80 external printOptions(Options options); | |
81 | |
82 @JS() | |
83 @anonymous | |
84 class Options { | |
85 external bool get responsive; | |
86 | |
87 external factory Options({bool responsive}); | |
88 } | |
89 ``` | |
90 | |
91 #### Passing functions to JavaScript. | |
92 | |
93 If you are passing a Dart function to a JavaScript API, you must wrap it using | |
94 `allowInterop` or `allowInteropCaptureThis`. | |
95 | |
96 ## Contributing and Filing Bugs | |
97 | |
98 Please file bugs and features requests on the [Github issue tracker][issues]. | |
99 | |
100 We also love and accept community contributions, from API suggestions to pull re
quests. | |
101 Please file an issue before beginning work so we can discuss the design and impl
ementation. | |
102 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. | |
103 | |
104 Code contributors must sign the | |
105 [Google Individual Contributor License Agreement](https://developers.google.com/
open-source/cla/individual?csw=1). | |
106 | |
107 [issues]: https://goo.gl/j3rzs0 | |
OLD | NEW |