dart-web-development

开发 Dart Web 应用

目录

• 核心约束
• JavaScript 互操作
• Web 工具与环境
• 工作流
• 示例

核心约束

• 使用 package:web： 始终优先使用 package:web，而不是旧版的 dart:html、dart:js 或 dart:js_util 库。
• 避免使用 dart:mirrors： Web 应用中绝不能使用 dart:mirrors，因为 Dart Web 编译完全不支持它。
• 使用 dart:js_interop： 使用 dart:js_interop 库实现所有 JavaScript 互操作。
• 优先使用扩展类型： 使用 Dart extension type 声明并结合 @JS 注解，定义 JavaScript 互操作边界和复杂的 JS 对象。

JavaScript 互操作

实现 JavaScript 互操作，以便在 Dart Web 应用中无缝集成 JS 库和浏览器 API。

• 使用 @JS() 注解库或外部声明，将其绑定到 JavaScript 对象。
• 使用 extension type 包装 JSObject 或其他 JS 类型。这为 JS 互操作提供零开销抽象边界。
• 跨越互操作边界时，使用 dart:js_interop 提供的特定 JS 类型（例如 JSString、JSNumber、JSObject、JSAny），而不是原生 Dart 类型（String、int）。

Web 工具与环境

使用 webdev 和 build_runner 管理开发生命周期、编译和测试。

• 依赖项： 确保在 pubspec.yaml 的 dev_dependencies 中列出 build_runner 和 build_web_compilers。如需测试，还要包含 build_test。
• 本地开发： 使用 webdev serve 启动开发服务器。它会使用开发编译器，支持增量更新和快速刷新。
• 调试： 在 webdev serve 后添加 --debug 标志，以启用 Dart DevTools。
• 生产构建： 使用 webdev build 生成经过压缩、可部署的 JavaScript 应用。

工作流

工作流：设置 Dart Web 项目

初始化或配置 Dart Web 项目时，复制并完成此检查清单：

• 添加所需的开发依赖项：dart pub add build_runner build_web_compilers --dev
• 添加 package:web 依赖项：dart pub add web
• 全局安装 webdev：dart pub global activate webdev
• 确认 pubspec.yaml 包含正确的依赖项。
• 运行 dart pub get，同步依赖项。

工作流：实现 JS 互操作

绑定新的 JavaScript 库或对象时，请按以下顺序操作：

• 导入 dart:js_interop。
• 为库或特定的外部函数／类添加 @JS() 注解。
• 使用 extension type Name._(JSObject _) implements JSObject 定义 JS 对象边界。
• 在扩展类型中声明 external 方法和属性，并使用 dart:js_interop 类型（例如 JSString）。
• 运行验证器 -> 检查编译错误 -> 修复 Dart 类型与 JS 类型之间的不匹配。

工作流：编译与服务

根据部署目标应用条件逻辑：

• 如果在本地开发：
  • 运行 webdev serve（默认端口为 8080）。
  • 如需使用 DevTools，运行 webdev serve --debug。
• 如果进行测试：
  • 运行 dart run build_runner test -- -p chrome。
• 如果构建生产版本：
  • 运行 webdev build --output web:build，将 web 目录编译到 build 目录。

示例

高保真 JS 互操作实现

此示例演示如何正确使用 dart:js_interop、package:web 和扩展类型，绑定一个假设的 JavaScript UserAuth 对象。

@JS()
library user_auth_interop;

import 'dart:js_interop';
import 'package:web/web.dart' as web;

// Bind to a global JavaScript function
@JS('console.log')
external void _log(JSAny? message);

// Define the JS interop boundary using an extension type
@JS('UserAuth')
extension type UserAuth._(JSObject _) implements JSObject {
  // External constructor
  external UserAuth(JSString apiKey);

  // External properties using JS types
  external JSString get currentUser;
  external set currentUser(JSString value);

  // External methods
  external void login(JSString username, JSString password);
  external JSBoolean isLoggedIn();
}

void main() {
  // Interact with the DOM using package:web
  final web.HTMLDivElement appDiv = web.document.querySelector('#app') as web.HTMLDivElement;
  appDiv.text = 'Initializing Auth...';

  // Instantiate and use the JS interop object
  final auth = UserAuth('api_key_123'.toJS);
  auth.login('admin'.toJS, 'password'.toJS);

  if (auth.isLoggedIn().toDart) {
    _log('User logged in successfully!'.toJS);
    appDiv.text = 'Welcome, ${auth.currentUser.toDart}';
  }
}