languages/dart-sdk
languages/dart-sdk
1
0
Fork 0
mirror of https://github.com/dart-lang/sdk synced 2024-09-05 16:41:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove some stale JS interop known differences

Browse source 
Remove sections describing differences between dart2js and ddc that
have since been resolved.

Both ddc and dart2js will require use of `allowInterop` in all but
unlikely edge cases. Both will be strict about argument types and count
as long as `allowInterop` is used.

Other fixes:
- Fix spelling of "supersedes".
- Use `List.from` over `list.cast().toList()` in example.

Change-Id: If4ce0926a4460ed41ddea2714ee3324c60770d62
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/136844
Commit-Queue: Nate Bosch <nbosch@google.com>
Auto-Submit: Nate Bosch <nbosch@google.com>
Reviewed-by: Nicholas Shahan <nshahan@google.com>
This commit is contained in:
Nate Bosch 2020-02-26 00:52:43 +00:00 committed by commit-bot@chromium.org
parent 9e03c2c506
commit 97cf54c58e
1 changed files with 4 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
pkg/js/README.md
View file

@ -5,7 +5,7 @@ that let you specify how your Dart code interoperates with JavaScript code.
The Dart-to-JavaScript compilers — dartdevc and dart2js — recognize these
annotations, using them to connect your Dart code with JavaScript.
**Important:** This library supercedes `dart:js`, so don't import `dart:js`.
**Important:** This library supersedes `dart:js`, so don't import `dart:js`.
Instead, import `package:js/js.dart`.
A second library in this package, `js_util`, provides low-level utilities
@ -104,8 +104,6 @@ class Options {
If you pass a Dart function to a JavaScript API as an argument,
wrap the Dart function using `allowInterop()` or `allowInteropCaptureThis()`.
**Warning:** Although dart2js requires `allowInterop()`, dartdevc does not.
To make a Dart function callable from JavaScript _by name_, use a setter
annotated with `@JS()`.
@ -151,25 +149,6 @@ conventions and type representation, and therefore have different challenges in
JavaScript interop. There are currently some known differences in behavior and
bugs in one or both compilers.
#### allowInterop is required in dart2js, optional in dartdevc
DDC uses the same calling conventions as JavaScript and so Dart functions passed
as callbacks can be invoked without modification. In dart2js the calling
conventions are different and so `allowInterop()` or `allowInteropCaptureThis()`
must be used for any callback.
**Workaround:**: Always use `allowInterop()` even when not required in dartdevc.
#### Callbacks allow extra ignored arguments in DDC
In JavaScript a caller may pass any number of "extra" arguments to a function
and they will be ignored. dartdevc follows this behavior, dart2js will have a runtime
error if a function is invoked with more arguments than expected.
**Workaround:** Write functions that take the same number of arguments as will
be passed from JavaScript. If the number is variable use optional positional
arguments.
#### Dartdevc and dart2js have different representation for Maps
Passing a `Map<String, String>` as an argument to a JavaScript function will
@ -210,8 +189,9 @@ from a JavaScript function cannot make guarantees about it's elements without
inspecting each one. At runtime a check like `result is List` may succeed, while
`result is List<String>` will always fail.
**Workaround:** Use a `.cast<String>().toList()` call to get a `List` with the
expected reified type at runtime.
**Workaround:** Use `.cast()` or construct a new `List` to get an instance with
the expected reified type. For instance if you want a `List<String>` use
`.cast<String>()` or `List<String>.from`.
#### The `JsObject` type from `dart:js` can't be used with `@JS()` annotation