dart-web-development

Dart Web アプリケーションの開発

目次

• コアとなる制約
• JavaScript との相互運用
• Web ツールと環境
• ワークフロー
• 例

コアとなる制約

• package:web を使用する： レガシーライブラリの dart:html、dart:js、dart:js_util よりも、常に package:web を優先してください。
• dart:mirrors は使用しない： Dart の Web コンパイルでは完全にサポートされていないため、Web アプリケーションで dart:mirrors を使用しないでください。
• dart:js_interop を使用する： JavaScript との相互運用はすべて、dart:js_interop ライブラリを使用して実装してください。
• Extension Type を優先する： JavaScript との相互運用の境界や複雑な JS オブジェクトは、@JS アノテーションと組み合わせた Dart の extension type 宣言を使って定義してください。

JavaScript との相互運用

JavaScript との相互運用を実装し、JS ライブラリやブラウザー API を Dart Web アプリにシームレスに統合してください。

• ライブラリまたは外部宣言に @JS() を付けて、JavaScript オブジェクトにバインドします。
• extension type を使って、JSObject やその他の JS 型をラップします。これにより、JS との相互運用にゼロコストの抽象化境界を設けられます。
• 相互運用の境界を越える際は、ネイティブの Dart 型（String、int）ではなく、dart:js_interop が提供する特定の JS 型（例：JSString、JSNumber、JSObject、JSAny）を使用します。

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 オブジェクトとの境界を定義します。
• extension type 内で 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 相互運用の実装例

この例では、仮想的な JavaScript の UserAuth オブジェクトをバインドするために、dart:js_interop、package:web、extension type を正しく使用する方法を示します。

@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}';
  }
}