跳到主要內容
目錄

Flutter 網頁應用程式初始化

目錄

本頁詳細說明 Flutter 網頁應用程式的初始化程序，以及如何自訂它。

引導啟動

#

flutter build web 命令會在建置輸出目錄 (build/web) 中產生一個名為 flutter_bootstrap.js 的腳本。此檔案包含初始化並執行您的 Flutter 應用程式所需的 JavaScript 程式碼。您可以將此腳本放入 Flutter 應用程式的 web 子目錄中的 index.html 檔案中，並使用 async-script 標籤來使用它。

html
<html>
  <body>
    <script src="flutter_bootstrap.js" async></script>
  </body>
</html>

或者，您也可以將 flutter_bootstrap.js 檔案的完整內容嵌入，方法是在您的 index.html 檔案中插入範本符號 {{flutter_bootstrap_js}}。

html
<html>
  <body>
    <script>
      {{flutter_bootstrap_js}}
    </script>
  </body>
</html>

當 index.html 檔案在建置步驟期間被複製到輸出目錄 (build/web) 時，{{flutter_bootstrap_js}} 符號會被 flutter_bootstrap.js 檔案的內容替換。

自訂初始化

#

預設情況下，flutter build web 會產生一個 flutter_bootstrap.js 檔案，該檔案會對您的 Flutter 應用程式進行簡單的初始化。但是，在某些情況下，您可能會有理由自訂此初始化過程，例如：

  • 為您的應用程式設定自訂的 Flutter 配置。
  • 變更 Flutter Service Worker 的設定。
  • 編寫自訂 JavaScript 程式碼，以在啟動過程的不同階段執行。

若要編寫您自己的自訂引導邏輯，而不是使用建置步驟產生的預設腳本，您可以將 flutter_bootstrap.js 檔案放置在專案的 web 子目錄中，它會被複製並取代建置產生的預設腳本使用。此檔案也會被視為範本，您可以插入幾個特殊符號，建置步驟會在將 flutter_bootstrap.js 檔案複製到輸出目錄時進行替換。下表列出了建置步驟將在 flutter_bootstrap.js 或 index.html 檔案中替換的符號：

符號替換為
{{flutter_js}}使 FlutterLoader 物件在 _flutter.loader 全域變數中可用的 JavaScript 程式碼。(請參閱下方的 _flutter.loader.load() API 章節以取得更多詳細資訊。)
{{flutter_build_config}}一個 JavaScript 陳述式，用於設定建置過程產生的中繼資料，該中繼資料提供 FlutterLoader 啟動應用程式所需的資訊。
{{flutter_service_worker_version}}代表 Service Worker 建置版本的唯一數字，可以作為 Service Worker 配置的一部分傳遞（請參閱下方的「Service Worker 設定」表）。
{{flutter_bootstrap_js}}如上所述，這會將 flutter_bootstrap.js 檔案的內容直接嵌入到 index.html 檔案中。請注意，此符號只能在 index.html 中使用，而不能在 flutter_bootstrap.js 檔案本身中使用。

撰寫自訂引導啟動指令碼

#

任何自訂的 flutter_bootstrap.js 腳本都需要包含三個元件才能成功啟動您的 Flutter 應用程式：

  • 一個 {{flutter_js}} 符號，以使 _flutter.loader 可用。
  • 一個 {{flutter_build_config}} 符號，它會將建置的相關資訊提供給啟動應用程式所需的 FlutterLoader。
  • 對 _flutter.loader.load() 的呼叫，這實際上會啟動應用程式。

最基本的 flutter_bootstrap.js 檔案看起來會像這樣：

js
{{flutter_js}}
{{flutter_build_config}}

_flutter.loader.load();

自訂 Flutter 載入器

#

可以透過可選參數呼叫 _flutter.loader.load() JavaScript API，以自訂初始化行為：

名稱描述JS 類型
config您的應用程式的 Flutter 配置。物件
onEntrypointLoaded引擎準備好初始化時呼叫的函式。接收一個 engineInitializer 物件作為其唯一的參數。函式

config 參數是一個物件，可以具有以下可選欄位：

名稱描述Dart 類型
assetBase應用程式 assets 目錄的基本 URL。當 Flutter 從與實際 Web 應用程式不同的網域或子目錄載入時，請新增此參數。當您將 Flutter Web 嵌入另一個應用程式或將其資源部署到 CDN 時，您可能需要此參數。字串
canvasKitBaseUrl從中下載 canvaskit.wasm 的基本 URL。字串
canvasKitVariant要下載的 CanvasKit 變體。您的選項包括：

1. auto：下載瀏覽器最適合的變體。此選項預設為此值。
2. full：下載可在所有瀏覽器中運作的完整 CanvasKit 變體。
3. chromium：下載使用與 Chromium 相容 API 的較小 CanvasKit 變體。警告：除非您計劃僅使用基於 Chromium 的瀏覽器，否則請勿使用 chromium 選項。		字串
canvasKitForceCpuOnly當 true 時，強制 CanvasKit 中僅使用 CPU 進行渲染（引擎將不會使用 WebGL）。布林值
canvasKitMaximumSurfacesCanvasKit 渲染器可以使用的最大疊加表面數量。雙精度浮點數
debugShowSemanticNodes如果為 true，Flutter 會在螢幕上可見地渲染語意樹（用於除錯）。布林值
entryPointBaseUrl您的 Flutter 應用程式進入點的基本 URL。預設為 "/"。字串
hostElementFlutter 將應用程式渲染至其中的 HTML 元素。如果未設定，Flutter Web 將接管整個頁面。HtmlElement
renderer指定目前 Flutter 應用程式的Web 渲染器，可以是 "canvaskit" 或 "skwasm"。字串

範例：根據 URL 查詢參數自訂 Flutter 設定

#

以下範例顯示了一個自訂的 flutter_bootstrap.js，允許使用者透過在網站 URL 中提供 renderer 查詢參數來選擇渲染器，例如：?renderer=skwasm。

js
{{flutter_js}}
{{flutter_build_config}}

const searchParams = new URLSearchParams(window.location.search);
const renderer = searchParams.get('renderer');
const userConfig = renderer ? {'renderer': renderer} : {};
_flutter.loader.load({
  config: userConfig,
});

此腳本會評估頁面的 URLSearchParams，以確定使用者是否傳遞了 renderer 查詢參數，然後變更 Flutter 應用程式的使用者配置。它還會傳遞要使用 Flutter Service Worker 的 Service Worker 設定，以及 Service Worker 版本。

onEntrypointLoaded 回呼

#

您也可以將 onEntrypointLoaded 回呼傳遞到 load API 中，以便在初始化過程的不同部分執行自訂邏輯。初始化過程分為以下幾個階段：

載入進入點腳本
一旦 Service Worker 初始化，並且瀏覽器已下載並執行 main.dart.js 進入點，load 函式就會呼叫 onEntrypointLoaded 回呼。Flutter 還會在開發期間的每次熱重啟時呼叫 onEntrypointLoaded。
初始化 Flutter 引擎
onEntrypointLoaded 回呼會接收一個引擎初始化器物件作為其唯一的參數。使用引擎初始化器 initializeEngine() 函式來設定執行階段配置，例如 multiViewEnabled: true，並啟動 Flutter Web 引擎。
執行應用程式
initializeEngine() 函式會傳回一個 Promise，該 Promise 會解析為一個應用程式執行器物件。應用程式執行器有一個單一方法 runApp()，用於執行 Flutter 應用程式。
將視圖新增至（或從）應用程式中移除視圖
runApp() 方法會傳回一個 Flutter 應用程式 物件。在多視圖模式下，可以使用 addView 和 removeView 方法從主應用程式管理應用程式視圖。若要瞭解更多資訊，請參閱嵌入模式。

範例：顯示進度指示器

#

為了在初始化過程中向應用程式使用者提供回饋，請使用為每個階段提供的掛鉤來更新 DOM。

js
{{flutter_js}}
{{flutter_build_config}}

const loading = document.createElement('div');
document.body.appendChild(loading);
loading.textContent = "Loading Entrypoint...";
_flutter.loader.load({
  onEntrypointLoaded: async function(engineInitializer) {
    loading.textContent = "Initializing engine...";
    const appRunner = await engineInitializer.initializeEngine();

    loading.textContent = "Running app...";
    await appRunner.runApp();
  }
});

除非另有說明，否則本網站上的文件皆反映了 Flutter 的最新穩定版本。頁面上次更新於 2024-11-12。 檢視原始碼 或 回報問題。