Dart-JavaScript Interop 使用与技术文档

2024-12-29 04:54:28作者：蔡丛锟

本文档旨在帮助用户安装、使用和理解 Dart-JavaScript Interop 项目。以下是关于如何安装、使用项目以及项目 API 的详细指南。

1. 安装指南

添加依赖

由于版本 0.4.0 尚未发布到 pub.dartlang.org，因此需要使用 Git 依赖来安装。

在您的 pubspec.yaml 文件中添加以下内容：

dependencies:
  js:
    git:
      url: git://github.com/dart-lang/js-interop.git

配置转换器

package:js 需要安装两个转换器，一个用于直接使用 package:js 生成 JavaScript 代理类的实现，另一个用于生成入口点所需的设置代码。

如果您的包直接使用 package:js 导出 API 或定义 JavaScript 代理，请在您的 pubspec.yaml 中添加以下内容：

transformers:
- js

如果您的包定义了 web/ 中的入口点，请在您的 pubspec.yaml 中添加以下内容：

transformers:
- js/initializer

如果您的包既定义了代理或导出，又具有 web/ 中的 HTML 入口点，则添加以下两个转换器：

transformers:
- js
- js/initializer

加载生成的 JavaScript

导出的 API 的 JavaScript 原型必须在页面中加载，以便其他 JavaScript 代码可以使用它们。这通过在 HTML 中包含 packages/js/interop.js 脚本来实现。构建应用程序时，该脚本被替换为生成的 JavaScript。interop 脚本必须在主 Dart 脚本之前加载。

<html>
  <head>
    <script src="packages/js/interop.js"></script>
  </head>
  <body>
    <script type="application/dart" src="main.dart"></script>
  </body>
</html>

初始化 Interop

您的 main() 方法必须调用 initializeJavaScript() 以导出 Dart 类并注册代理。此调用应尽早进行，最好是在最开始。

library main;

import 'package:js/js.dart';

main() {
  initializeJavaScript();
}

2. 项目使用说明

定义类型化 JavaScript 代理

类型化 JavaScript 代理是表示 JavaScript 对象的类，并具有定义良好的 Dart API，包括类型注解、构造函数，甚至可选和命名参数。它们分为两部分定义：

定义接口的抽象类
实现接口的的具体类（通过镜子或 js 转换器自动实现）

抽象类的定义如下：

必须扩展 JsInterface
必须具有构造函数签名 C.created(JsObject o)
抽象方法或访问器自动为您调用 JavaScript
理想情况下，所有参数和返回值都应具有类型注解
如果要从 Dart 创建新实例，请添加工厂构造函数
对于 Map 和 List，需要复制才能在 JavaScript 中使用，对任何接收 Map 或 List 的参数添加 @jsify 注解

具体实现类的定义如下：

必须扩展接口类
必须具有 created 构造函数
必须具有 @JsProxy 注解
应具有 noSuchMethod 方法以转发到超类，以抑制警告

导出 Dart API 到 JavaScript

您可以使用 @Export 注解将类、函数、变量甚至整个库导出到 JavaScript。

导出类的示例：

library a;

import 'package:js/js.dart';

@Export()
class A {
  String name;

  A();

  A.withName(this.name);
}

在 JavaScript 中使用：

var a1 = new dart.a.A();
a1 instanceof dart.a.A; // true
a1.name; // null
a1.name = 'red'; // 在 Dart 中设置值

// 支持命名构造函数
var a2 = new dart.a.A.withName('blue');
a2 instanceof dart.a.A;
a2.name; // 'blue'