From 69b3e85068f2fa497997d47521be031e679f26e3 Mon Sep 17 00:00:00 2001 From: Marya <111139605+MaryaBelanger@users.noreply.github.com> Date: Fri, 27 Jan 2023 15:00:11 -0800 Subject: [PATCH] [2.19] Add next-generation preview section to js-interop page (#4528) Staged: https://dart-dev--pr4528-future-js-interop-zfqketfc.web.app/web/js-interop Fixes #4450 --------- Co-authored-by: Parker Lougheed --- src/web/js-interop.md | 101 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 100 insertions(+), 1 deletion(-) diff --git a/src/web/js-interop.md b/src/web/js-interop.md index af264758db..be6892a2e8 100644 --- a/src/web/js-interop.md +++ b/src/web/js-interop.md @@ -2,7 +2,6 @@ title: JavaScript interoperability short-title: JS interop description: "Use package:js to integrate JavaScript code into your Dart web app." -toc: false --- The [Dart web platform](/overview#web-platform) supports calling @@ -22,3 +21,103 @@ For help using the `js` package, see the following: [js-api]: {{site.pub-api}}/js [sass]: {{site.pub-pkg}}/sass +## Next-generation JS interop preview + +{{site.alert.note}} + This interop feature is **experimental**, + and [in active development](https://github.com/dart-lang/sdk/issues/35084). +{{site.alert.end}} + +Dart's JS interop story is currently evolving. +Many of the features that enable future JS interop +are ready to experiment with as of Dart version 2.19. +These features support the existing production +and development web compilers, +as well as Dart's in-progress Wasm compiler ([`dart2wasm`][]). + +For a glimpse into the next generation of JS interop, +you can refactor your code to conform to +the new syntax and semantics now. +Doing so will likely not prevent the need to refactor again +once [Dart 3][] lands, as the features are still in development. +However, the features available for preview are much closer +to future JS interop than any pattern supported today. +So, there are a few reasons to try them out now: + +* New JS interop developers can learn and build with future JS interop + so they won't have to unlearn obsolete patterns in a few months. +* Existing JS interop developers eager to experiment with + the latest features in JS interop + or with `dart2wasm` when it becomes available. +* Potentially ease transition of existing JS interop code + once migration becomes necessary. + +The following sections are the set of features +expected to work across compilers for JS interop. + +*Requirements:* + +* Dart SDK constraint: `>= 2.19` +* [`package:js`][] constraint: `>= 0.6.6` + +[`dart2wasm`]: https://github.com/dart-lang/sdk/blob/main/pkg/dart2wasm/dart2wasm.md#running-dart2wasm +[Dart 3]: https://medium.com/dartlang/dart-3-alpha-f1458fb9d232 +[`package:js`]: {{site.pub-pkg}}/js + +### `package:js` + +The key feature of next-generation JS interop is [static interop][]. +We recommend using static interop as the default for `package:js`, +as it is more declarative, more likely to be optimized, +more likely to perform better, and required for `dart2wasm`. +Static interop addresses several gaps in the existing JS interop story: + +* **Missing features:** Static interop enables previously + unavailable features, like easily wrapping and transforming APIs, + renaming members, and static checking. + +* **Inconsistencies:** Static interop makes backends more consistent, + so development and production web compilers + won't behave as differently as before. + +* **Clarity:** Static interop takes a step towards making + JS interop more idiomatic in Dart, + and making the boundary between the two languages more visible. + For example, it enforces that JS classes are not meant to be mixed with Dart + (dynamic calls aren't allowed, + and JS interop types cannot be implemented as a Dart class). + +You can implement static interop using +the `package:js` annotation [`@staticInterop`][]. +The set of features for future static interop currently includes: + +* `@staticInterop` interfaces + * External factory constructors with and without `@anonymous` + * External `static` class members + * External non-`static` extension members on a `@staticInterop` + class (fields, getters, setters, methods) + * Non-external extension members on a `@staticInterop` class +* Top-level external members +* [`@JSExport`][] for mocking and exports + +To learn how to implement static interop and see examples, +visit the [static interop][] specification. + +[`@staticInterop`]: {{site.pub-api}}/js/latest/js/staticInterop-constant.html +[static interop]: {{site.pub-pkg}}/js#staticinterop +[`@JSExport`]: {{site.pub-pkg}}/js#jsexport-and-js_utilcreatedartexport + +### `dart:js_util` + +[`dart:js_util`][] provides low-level interop API +and is supported by the JS and `dart2wasm` backends. +`dart:js_util` can provide more flexibility, +for example, in potential, rare edge cases we haven't yet +accounted for where static interop is not expressive enough. + +However, it is not as ergonomic, and we do not plan +to optimize it in the same way as static interop. +As a result, we highly recommend using static interop over +`dart:js_util` whenever it's possible. + +[`dart:js_util`]: {{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-js_util/dart-js_util-library.html