自定义 Web 应用程序的初始化
你可以使用 flutter.js
提供的 _flutter.loader
JavaScript API
来自定义 Flutter 应用程序在 web 上的初始化方式。该 API 可以用于在 CSS 中显示加载指示器,也可以根据条件阻止加载应用程序,还可以等待用户按下按钮后再显示应用程序。
初始化过程分为以下阶段:
加载入口脚本
获取 main.dart.js
脚本并初始化 service worker。
初始化 Flutter 引擎
通过下载所需资源(如静态资源、字体和 CanvasKit)来初始化 Flutter web 引擎。
运行应用程序
为 Flutter 应用程序准备 DOM 并运行。
本篇介绍了如何自定义初始化过程各个阶段的行为。
入门指南
#默认情况下,flutter create
指令生成的 index.html
文件包含一个 script 标签,用于调用 flutter.js
文件中的 loadEntrypoint
:
<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>
一旦 Service Worker 初始化,且浏览器下载并运行了 main.dart.js
入口,
loadEntrypoint
函数就会调用 onEntrypointLoaded
回调。
Flutter 还会在开发过程中每次热重载时调用 onEntrypointLoaded
。
onEntrypointLoaded
回调接收一个 engine initializer 对象作为唯一参数。使用 engine initializer 设置运行时的配置,并启动 Flutter Web 引擎。
initializeEngine()
函数返回一个包含了 app runner 对象的 Promise
。
app runner 只有一个 runApp()
方法,它用于运行 Flutter 应用程序。
自定义 web 应用程序的初始化
#在本节中,了解如何自定义应用程序初始化的各个阶段。
加载入口
#loadEntrypoint
方法接受以下参数:
entrypointUrl |
"main.dart.js" 。 |
String |
onEntrypointLoaded |
engineInitializer 对象。 |
Function |
serviceWorker |
flutter_service_worker.js 加载器的配置。(如果未设置,则不会使用 service worker)。 |
Object |
serviceWorker
JavaScript 对象接受以下属性:
serviceWorkerUrl |
serviceWorkerVersion 会附加到 URL 中。默认为 "flutter_service_worker.js?v=" 。 |
String |
serviceWorkerVersion |
serviceWorkerVersion 变量 并在 index.html 中运用。 |
String |
timeoutMillis |
4000 。 |
Number |
初始化引擎
#从 Flutter 3.7.0 版本
起,你可以使用 initializeEngine
方法通过纯 JavaScript 对象配置 Flutter web 引擎的多个运行时选项。
你可以添加以下任何可选参数:
assetBase |
assets 目录的根 URL。当 Flutter 从实际 web 应用不同的域或子目录加载时,请添加此 URL。当你将 Flutter web 嵌入另一个应用程序,或将其静态资源部署到 CDN 时,可能需要使用此 URL。 |
String |
canvasKitBaseUrl |
canvaskit.wasm 的根 URL。 |
String |
canvasKitVariant |
1. auto :为浏览器下载最佳版本。(默认值)2. full :下载适用于所有浏览器的 CanvasKit 完整版。3. chromium :下载较小的 CanvasKit,该版本使用与 Chromium 兼容的 API。警告:除非你只打算使用基于 Chromium 的浏览器,否则不要使用 chromium 值。 |
String |
canvasKitForceCpuOnly |
true 时,强制在 CanvasKit 中只使用 CPU 进行渲染(引擎不会使用 WebGL)。 |
bool |
canvasKitMaximumSurfaces |
double |
|
debugShowSemanticNodes |
true ,Flutter 会在屏幕上明显呈现 semantics 语义树(用于调试)。 |
bool |
hostElement |
HtmlElement |
|
renderer |
"canvaskit" 或 "html" 。 |
String |
引擎配置示例
#通过 initializeEngine
方法,你可以向 Flutter 应用程序传递上述任何配置参数。
请看下面这个例子。
你的 Flutter 应用程序使用 id="flutter_app"
的 HTML 元素,并使用 canvaskit
渲染器。
JavaScript 代码就像下面这样:
onEntrypointLoaded: async function(engineInitializer) {
let appRunner = await engineInitializer.initializeEngine({
hostElement: document.querySelector("#flutter_app"),
renderer: "canvaskit"
});
appRunner.runApp();
}
有关每个参数的详细解释,请查阅 web 引擎 configuration.dart
文件中,文档的 "Runtime parameters" 部分。
跳过此步骤
#与其在 engine initializer 上调用 initializeEngine()
(然后在 app runner 上调用 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 Gallery 的 初始化代码。
升级旧项目
#如果你的项目是在 Flutter 2.10 或更早版本中创建的,你可以通过运行 flutter create
指令创建一个带有最新初始化模板的 index.html
文件,方法如下。
首先,删除 /web
目录中的文件。
然后,在项目目录下运行以下指令:
flutter create . --platforms=web
除非另有说明,本文档之所提及适用于 Flutter 的最新稳定版本,本页面最后更新时间: 2024-09-04。 查看文档源码 或者 为本页面内容提出建议。