dart-web-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dart-web-js-interop

Goal

目标

Configures Dart web applications for modern JavaScript interoperability using

dart:js_interop

and

package:web

, and manages the build, serve, and test lifecycle using

webdev

. Assumes a standard Dart web environment requiring integration with external JavaScript libraries or browser APIs.

使用

dart:js_interop

和

package:web

为Dart Web应用配置现代化JavaScript互操作能力，并通过

webdev

管理构建、启动服务和测试生命周期。适用于需要与外部JavaScript库或浏览器API集成的标准Dart Web环境。

Decision Logic

决策逻辑

Evaluate the user's current objective to determine the appropriate action path:

Project Setup: If the project lacks web build tools, proceed to dependency configuration.
JS Binding Creation: If the user needs to call JS from Dart, implement
```
@JS
```
annotations with Extension Types.
Local Development: If the user is actively developing, utilize
```
webdev serve
```
with hot-reload capabilities.
Production Deployment: If the user is preparing for release, utilize
```
webdev build
```
.
Testing: If the user needs to validate web components, utilize
```
build_runner test
```
.

评估用户当前目标以确定合适的操作路径：

项目初始化： 如果项目缺少Web构建工具，进入依赖配置流程。
JS绑定创建： 如果用户需要从Dart调用JS代码，使用扩展类型（Extension Types）实现
```
@JS
```
注解。
本地开发： 如果用户正处于活跃开发阶段，使用支持热重载能力的
```
webdev serve
```
。
生产部署： 如果用户正在准备发布版本，使用
```
webdev build
```
。
测试： 如果用户需要验证Web组件，使用
```
build_runner test
```
。

Instructions

操作指引

Configure Web Dependencies Ensure the project has the required development and web dependencies. Modify

pubspec.yaml

to include

build_runner

build_web_compilers

, and

package:web

yaml

dependencies:
  web: ^0.5.0 # Use latest compatible version

dev_dependencies:
  build_runner: ^2.4.0
  build_web_compilers: ^4.0.0
  build_test: ^3.0.0 # If testing is required

Run

dart pub get

to resolve dependencies. Validate-and-Fix: If dependency resolution fails, verify SDK constraints in

pubspec.yaml

support Dart 3.3+ (required for modern JS interop).

Implement JavaScript Interoperability Define JavaScript boundaries using

dart:js_interop

and Extension Types. Do not use legacy

dart:html

or older interop libraries.

dart

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

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

// Bind to a JavaScript object/class using Extension Types
@JS('MyJSClass')
extension type MyDartWrapper._(JSObject _) implements JSObject {
  external MyDartWrapper(JSString name);
  
  external JSString get name;
  external set name(JSString value);
  
  external void doSomething();
}

void main() {
  // Example usage interacting with the DOM via package:web
  final div = web.document.createElement('div') as web.HTMLDivElement;
  div.text = 'Hello from Dart!';
  web.document.body?.append(div);

  // Example usage of custom JS interop
  final myObj = MyDartWrapper('Test'.toJS);
  myObj.doSomething();
}

Initialize Local Development Server STOP AND ASK THE USER: "Do you need to run the development server on a specific port, or enable Dart DevTools debugging?" If standard development is requested, start the server using
```
webdev
```
:
bash
```
# Standard serve (defaults to localhost:8080)
webdev serve

# Serve with Dart DevTools enabled
webdev serve --debug

# Serve on a custom port
webdev serve web:8083
```
Execute Production Build Compile the application for production deployment. This generates minified JavaScript.
bash
```
# Build the 'web' directory into the 'build' directory
webdev build --output web:build
```
Validate-and-Fix: Inspect the output directory. If the build fails due to missing builders, ensure
```
build_web_compilers
```
is correctly listed in
```
dev_dependencies
```
.

Run Web Tests Execute component or unit tests in a browser environment.

bash

# Run tests on the Chrome platform
dart run build_runner test -- -p chrome

配置Web依赖 确保项目包含所需的开发依赖和Web依赖。修改

pubspec.yaml

引入

build_runner

、

build_web_compilers

和

package:web

。

yaml

dependencies:
  web: ^0.5.0 # Use latest compatible version

dev_dependencies:
  build_runner: ^2.4.0
  build_web_compilers: ^4.0.0
  build_test: ^3.0.0 # If testing is required

运行

dart pub get

解析依赖。 验证与修复： 如果依赖解析失败，检查

pubspec.yaml

中的SDK约束是否支持Dart 3.3+（现代化JS互操作的必要条件）。

实现JavaScript互操作 使用

dart:js_interop

和扩展类型定义JavaScript边界。不要使用旧版的

dart:html

或更早的互操作库。

dart

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

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

// Bind to a JavaScript object/class using Extension Types
@JS('MyJSClass')
extension type MyDartWrapper._(JSObject _) implements JSObject {
  external MyDartWrapper(JSString name);
  
  external JSString get name;
  external set name(JSString value);
  
  external void doSomething();
}

void main() {
  // Example usage interacting with the DOM via package:web
  final div = web.document.createElement('div') as web.HTMLDivElement;
  div.text = 'Hello from Dart!';
  web.document.body?.append(div);

  // Example usage of custom JS interop
  final myObj = MyDartWrapper('Test'.toJS);
  myObj.doSomething();
}

初始化本地开发服务器 请先询问用户： "你是否需要在指定端口运行开发服务器，或者启用Dart DevTools调试功能？" 如果用户需要标准开发模式，使用
```
webdev
```
启动服务器：
bash
```
# Standard serve (defaults to localhost:8080)
webdev serve

# Serve with Dart DevTools enabled
webdev serve --debug

# Serve on a custom port
webdev serve web:8083
```
执行生产构建 编译应用用于生产部署，该操作会生成压缩后的JavaScript代码。
bash
```
# Build the 'web' directory into the 'build' directory
webdev build --output web:build
```
验证与修复： 检查输出目录。如果构建因缺少构建器失败，确认
```
build_web_compilers
```
已正确添加到
```
dev_dependencies
```
中。

运行Web测试 在浏览器环境中执行组件或单元测试。

bash

# Run tests on the Chrome platform
dart run build_runner test -- -p chrome

Constraints

约束条件

DO NOT use

dart:html

dart:js

, or

dart:js_util

. Strictly use

package:web

and

dart:js_interop

DO NOT use
```
dart:mirrors
```
under any circumstances; it is unsupported in Dart web applications.
MUST use
```
extension type
```
for defining complex JavaScript object bindings.
MUST annotate external JS declarations with
```
@JS()
```
.
MUST convert Dart types to JS types explicitly (e.g.,
```
'string'.toJS
```
) when passing arguments to JS interop functions.

Related Skills:

dart-migration-versioning

dart-compilation-deployment

禁止使用

dart:html

、

dart:js

或

dart:js_util

，必须严格使用

package:web

和

dart:js_interop

。

任何情况下都禁止使用
```
dart:mirrors
```
，Dart Web应用不支持该库。
必须使用
```
extension type
```
定义复杂的JavaScript对象绑定。
必须为外部JS声明添加
```
@JS()
```
注解。
向JS互操作函数传递参数时，必须显式将Dart类型转换为JS类型（例如
```
'string'.toJS
```
）。