Web アプリの初期化のカスタマイズ

コンテンツ

Flutter アプリを Web 上で初期化する方法をカスタマイズできますを使用して_flutter.loaderJavaScript APIの提供flutter.js。この API を使用すると、CSS で読み込みインジケーターを表示できます。条件に基づいてアプリの読み込みを防止し、または、ユーザーがボタンを押すまで待ってからアプリを表示します。

初期化プロセスは次の段階に分かれています。

エントリポイントスクリプトのロード: をフェッチしますmain.dart.jsスクリプトを作成し、Service Worker を初期化します。
Flutter エンジンの初期化: 必要なリソースをダウンロードして Flutter の Web エンジンを初期化しますアセット、フォント、CanvasKit など。
アプリの実行: Flutter アプリの DOM を準備して実行します。

このページでは、動作をカスタマイズする方法を示します初期化プロセスの各段階で。

入門

デフォルトでは、index.htmlファイルによって生成されるflutter create指図スクリプトタグが含まれていますそれは電話しますloadEntrypointからflutter.jsファイル：

<html>
  <head>
    <!-- ... -->
    <script src="flutter.js" defer></script>
  </head>
  <body>
    <script>
      window.addEventListener('load', function (ev) {
        // Download main.dart.js
        _flutter.loader.loadEntrypoint({
          serviceWorker: {
            serviceWorkerVersion: serviceWorkerVersion,
          },
          onEntrypointLoaded: async function(engineInitializer) {
            // Initialize the Flutter engine
            let appRunner = await engineInitializer.initializeEngine();
            // Run the app
            await appRunner.runApp();
          }
        });
      });
    </script>
  </body>
</html>

のloadEntrypoint関数が呼び出すonEntrypointLoaded折り返し電話 Service Worker が初期化されると、main.dart.jsエントリーポイントがダウンロードされ、ブラウザによって実行されます。 Flutter も呼び出しますonEntrypointLoaded開発中のホットリスタートごとに。

のonEntrypointLoadedコールバックはエンジンイニシャライザオブジェクトとして唯一のパラメータです。エンジン初期化子を使用してランタイムを設定する構成を変更し、Flutter Web エンジンを起動します。

のinitializeEngine()関数は次の値を返しますPromiseそれは次のように解決されますアプリランナー物体。アプリランナーには、単一のメソッド、runApp(), Flutter アプリを実行します。

Web アプリの初期化のカスタマイズ

このセクションで、アプリの初期化の各段階をカスタマイズする方法を学びます。

エントリポイントのロード

のloadEntrypointメソッドは次のパラメータを受け入れます。

名前	説明	JS タイプ
`entrypointUrl`	Flutter アプリのエントリポイントの URL。デフォルトは`"main.dart.js"`。	`String`
`onEntrypointLoaded`	エンジンを初期化する準備ができたときに呼び出される関数。を受け取ります`engineInitializer`object を唯一のパラメータとして使用します。	`Function`
`serviceWorker`	の構成は、`flutter_service_worker.js`ローダ。 (設定されていない場合、Service Worker は使用されません。)	`Object`

のserviceWorkerJavaScript オブジェクトは次のプロパティを受け入れます。

名前	説明	JS タイプ
`serviceWorkerUrl`	Service Worker JS ファイルの URL。の`serviceWorkerVersion`が URL に追加されます。デフォルトは`"flutter_service_worker.js?v="`	`String`
`serviceWorkerVersion`	合格の`serviceWorkerVersion`変数のビルドプロセスによって設定されます`index.html`ファイル。	`String`
`timeoutMillis`	Service Worker ロードのタイムアウト値。デフォルトは`4000`。	`Number`

エンジンの初期化

現在 flutter 3.7.0を使用できます。initializeEngineする方法 Flutter Web エンジンのいくつかの実行時オプションを、プレーンな JavaScript オブジェクト。

次のオプションのパラメータのいずれかを追加できます。

名前	説明	ダーツの種類
`assetBase`	のベース URL`assets`アプリのディレクトリ。 Flutter が実際の Web アプリとは異なるドメインまたはサブディレクトリから読み込まれる場合にこれを追加します。 Flutter Web を別のアプリに埋め込むとき、またはそのアセットを CDN にデプロイするときに、これが必要になる場合があります。	`String`
`canvasKitBaseUrl`	ここからのベース URL`canvaskit.wasm`ダウンロードされます。	`String`
`canvasKitVariant`	ダウンロードする CanvasKit バリアント。オプションの範囲は次のとおりです。 1.`auto`: ブラウザに最適なバリアントをダウンロードします。このオプションのデフォルトはこの値です。 2.`full`: すべてのブラウザで動作する CanvasKit の完全版をダウンロードします。 3.`chromium`: Chromium 互換 API を使用する CanvasKit のより小さいバリアントをダウンロードします。警告：使用しないでください。`chromium`Chromium ベースのブラウザのみを使用する予定がない限り、オプションを選択してください。	`String`
`canvasKitForceCpuOnly`	いつ`true`、CanvasKit で CPU のみのレンダリングを強制します (エンジンは WebGL を使用しません)。	`bool`
`canvasKitMaximumSurfaces`	CanvasKit レンダラーが使用できるオーバーレイサーフェスの最大数。	`double`
`debugShowSemanticNodes`	もしも`true`, Flutter は、(デバッグ用に) セマンティクスツリーを画面上に視覚的にレンダリングします。	`bool`
`hostElement`	Flutter がアプリをレンダリングする HTML 要素。設定されていない場合、Flutter Web がページ全体を引き継ぎます。	`HtmlElement`
`renderer`	を指定しますウェブレンダラー現在の Flutter アプリケーションの場合、次のいずれかです。`"canvaskit"`また`"html"`。	`String`

エンジン構成例

のinitializeEngineこのメソッドを使用すると、任意の設定を渡すことができます上記のパラメータを Flutter アプリに追加します。

次の例を考えてみましょう。

Flutter アプリは、次の HTML 要素をターゲットにする必要があります。id="flutter_app"と使用canvaskitレンダラー。結果の JavaScript コードは次のようになります。以下：

onEntrypointLoaded: async function(engineInitializer) {
  let appRunner = await engineInitializer.initializeEngine({
    hostElement: document.querySelector("#flutter_app"),
    renderer: "canvaskit"
  });
  appRunner.runApp();
}

各パラメータの詳細な説明については、「「実行時パラメータ」のドキュメントセクションconfiguration.dartWebエンジンのファイルです。

このステップをスキップする

電話をかける代わりにinitializeEngine()エンジンイニシャライザ上 (そしてその後)runApp()アプリケーションランナー上で）、呼び出すことができますautoStart()にエンジンをデフォルト構成で初期化し、アプリを起動します。初期化が完了した直後:

_flutter.loader.loadEntrypoint({
  serviceWorker: {
    serviceWorkerVersion: serviceWorkerVersion,
  },
  onEntrypointLoaded: async function(engineInitializer) {
    await engineInitializer.autoStart();
  }
});

例: 進行状況インジケーターを表示する

アプリケーションのユーザーにフィードバックを与えるには初期化プロセス中に、各ステージに提供されているフックを使用して DOM を更新します。

<html>
  <head>
    <!-- ... -->
    <script src="flutter.js" defer></script>
  </head>
  <body>
    <div id="loading"></div>
    <script>
      window.addEventListener('load', function(ev) {
        var loading = document.querySelector('#loading');
        loading.textContent = "Loading entrypoint...";
        _flutter.loader.loadEntrypoint({
          serviceWorker: {
            serviceWorkerVersion: serviceWorkerVersion,
          },
          onEntrypointLoaded: async function(engineInitializer) {
            loading.textContent = "Initializing engine...";
            let appRunner = await engineInitializer.initializeEngine();

            loading.textContent = "Running app...";
            await appRunner.runApp();
          }
        });
      });
    </script>
  </body>
</html>

CSS アニメーションを使用したより実用的な例については、を参照してください初期化コード flutterギャラリー用。

古いプロジェクトのアップグレード

プロジェクトが Flutter 2.10 以前で作成された場合、新しいものを作成できますindex.htmlファイル最新の初期化テンプレートを使用して実行します。flutter create次のように。

まず、ファイルを/webディレクトリ。

次に、プロジェクトディレクトリから次のコマンドを実行します。

$ flutter create . --platforms=web