Flutter 视图和 Web 内容可以组合起来,以不同的方式生成 Web 应用。根据您的用例选择以下一种:

全页模式

#

在全页模式下,Flutter Web 应用将控制整个浏览器窗口,并在渲染时完全覆盖其视口。

这是新 Flutter Web 项目的默认嵌入模式,无需额外配置。

html
<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <script src="flutter_bootstrap.js" defer></script>
  </body>
</html>

当 Flutter Web 在没有引用 multiViewEnabledhostElement 的情况下启动时,它将使用全页模式。

要了解有关 flutter_bootstrap.js 文件的更多信息,请参阅自定义应用初始化

iframe 嵌入

#

在通过 iframe 嵌入 Flutter Web 应用时,建议使用全页模式。嵌入 iframe 的页面可以根据需要调整其大小和位置,Flutter 将完全填充它。

html
<iframe src="https://url-to-your-flutter/index.html"></iframe>

要了解有关 iframe 的优缺点的更多信息,请参阅 MDN 上的Inline Frame element 文档。

嵌入模式

#

Flutter Web 应用还可以将内容渲染到另一个 Web 应用的任意数量的元素(通常是 div)中;这被称为“嵌入模式”(或“多视图”)。

在此模式下

  • Flutter Web 应用可以启动,但在添加第一个“视图”并调用 addView 之前不会渲染。
  • 主机应用可以从嵌入的 Flutter Web 应用添加或移除视图。
  • Flutter 应用会在视图添加或移除时收到通知,以便相应地调整其小部件。

启用多视图模式

#

通过在 initializeEngine 方法中设置 multiViewEnabled: true 来启用多视图模式,如下所示:

flutter_bootstrap.js
js
{{flutter_js}}
{{flutter_build_config}}

_flutter.loader.load({
  onEntrypointLoaded: async function onEntrypointLoaded(engineInitializer) {
    let engine = await engineInitializer.initializeEngine({
      multiViewEnabled: true, // Enables embedded mode.
    });
    let app = await engine.runApp();
    // Make this `app` object available to your JS app.
  }
});

从 JS 管理 Flutter 视图

#

要添加或移除视图,请使用 runApp 方法返回的 app 对象。

js
// Adding a view...
let viewId = app.addView({
  hostElement: document.querySelector('#some-element'),
});

// Removing viewId...
let viewConfig = app.removeView(viewId);

从 Dart 处理视图更改

#

视图的添加和移除通过 WidgetsBinding 类的didChangeMetrics 方法暴露给 Flutter。

附加到 Flutter 应用的所有视图的完整列表可通过 WidgetsBinding.instance.platformDispatcher.views 可迭代对象获得。这些视图的类型为FlutterView

要将内容渲染到每个 FlutterView 中,您的 Flutter 应用需要创建一个View 小部件View 小部件可以被分组在ViewCollection 小部件下。

以下示例来自“多视图游乐场”,它将上述内容封装在 MultiViewApp 小部件中,该小部件可用作应用的根小部件。一个WidgetBuilder 函数会针对每个 FlutterView 运行。

multi_view_app.dart
dart
import 'dart:ui' show FlutterView;
import 'package:flutter/widgets.dart';

/// Calls [viewBuilder] for every view added to the app to obtain the widget to
/// render into that view. The current view can be looked up with [View.of].
class MultiViewApp extends StatefulWidget {
  const MultiViewApp({super.key, required this.viewBuilder});

  final WidgetBuilder viewBuilder;

  @override
  State<MultiViewApp> createState() => _MultiViewAppState();
}

class _MultiViewAppState extends State<MultiViewApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _updateViews();
  }

  @override
  void didUpdateWidget(MultiViewApp oldWidget) {
    super.didUpdateWidget(oldWidget);
    // Need to re-evaluate the viewBuilder callback for all views.
    _views.clear();
    _updateViews();
  }

  @override
  void didChangeMetrics() {
    _updateViews();
  }

  Map<Object, Widget> _views = <Object, Widget>{};

  void _updateViews() {
    final Map<Object, Widget> newViews = <Object, Widget>{};
    for (final FlutterView view in WidgetsBinding.instance.platformDispatcher.views) {
      final Widget viewWidget = _views[view.viewId] ?? _createViewWidget(view);
      newViews[view.viewId] = viewWidget;
    }
    setState(() {
      _views = newViews;
    });
  }

  Widget _createViewWidget(FlutterView view) {
    return View(
      view: view,
      child: Builder(
        builder: widget.viewBuilder,
      ),
    );
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ViewCollection(views: _views.values.toList(growable: false));
  }
}

有关更多信息,请查看 API 文档中的WidgetsBinding mixin,或开发期间使用的多视图游乐场存储库

在 Dart 中将 runApp 替换为 runWidget

#

Flutter 的runApp 函数假定至少有一个可用视图可供渲染(implicitView)。然而,在 Flutter Web 的多视图模式下,implicitView 不再存在,因此 runApp 将开始因 Unexpected null value 错误而失败。

在多视图模式下,您的 main.dart 必须改调用runWidget 函数。它不需要 implicitView,并且只会渲染到已显式添加到您应用中的视图。

以下示例使用上面描述的 MultiViewApp 在每个可用的 FlutterView 上渲染 MyApp() 小部件的副本。

main.dart
dart
void main() {
  runWidget(
    MultiViewApp(
      viewBuilder: (BuildContext context) => const MyApp(),
    ),
  );
}

识别视图

#

每个 FlutterView 在附加时都会由 Flutter 分配一个标识符。此 viewId 可用于唯一标识每个视图、检索其初始配置或决定在其上渲染的内容。

渲染的 FlutterViewviewId 可以通过其 BuildContext 检索,如下所示:

dart
class SomeWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Retrieve the `viewId` where this Widget is being built:
    final int viewId = View.of(context).viewId;
    // ...

类似地,从 MultiViewAppviewBuilder 方法中,可以这样检索 viewId

dart
MultiViewApp(
  viewBuilder: (BuildContext context) {
    // Retrieve the `viewId` where this Widget is being built:
    final int viewId = View.of(context).viewId;
    // Decide what to render based on `viewId`...
  },
)

阅读有关View.of 构造函数的更多信息。

初始视图配置

#

Flutter 视图在启动时可以从 JS 接收任何初始化数据。这些值通过 addView 方法的 initialData 属性传递,如下所示:

js
// Adding a view with initial data...
let viewId = app.addView({
  hostElement: someElement,
  initialData: {
    greeting: 'Hello, world!',
    randomValue: Math.floor(Math.random() * 100),
  }
});

在 Dart 中,initialData 是一个 JSAny 对象,可通过 dart:ui_web 库中的顶层 views 属性访问。数据通过当前视图的 viewId 访问,如下所示:

dart
final initialData = ui_web.views.getInitialData(viewId) as YourJsInteropType;

要了解如何定义 YourJsInteropType 类来映射从 JS 传递的 initialData 对象,使其在 Dart 程序中类型安全,请参阅 Dart.dev 上的JS Interoperability

视图约束

#

默认情况下,嵌入式 Flutter Web 视图将其 hostElement 的大小视为不可变属性,并将其布局严格限制在可用空间内。

在 Web 上,元素的固有尺寸会影响页面布局(例如,imgp 标签会围绕它们重排内容)。

添加视图到 Flutter Web 时,您可能会使用一些约束来配置它,这些约束会告知 Flutter 视图需要如何布局。

js
// Adding a view with initial data...
let viewId = app.addView({
  hostElement: someElement,
  viewConstraints: {
    maxWidth: 320,
    minHeight: 0,
    maxHeight: Infinity,
  }
});

从 JS 传递的视图约束需要与 Flutter 嵌入的 hostElement 的 CSS 样式兼容。例如,Flutter 不会尝试“修复”矛盾的常量,例如在 CSS 中传递 max-height: 100px,而在 Flutter 中传递 maxHeight: Infinity

要了解更多信息,请查看ViewConstraints理解约束

自定义元素 (hostElement)

#

在 Flutter 3.10 和 3.24 之间
您可以将单视图 Flutter Web 应用嵌入到您网页的任何 HTML 元素中。

要告知 Flutter Web 将哪个元素渲染到其中,请向 _flutter.loader.load 函数传递一个包含 config 字段的对象,该对象将 HTMLElement 指定为 hostElement

js
_flutter.loader.load({
  config: {
    hostElement: document.getElementById('flutter_host'),
  }
});

要了解有关其他配置选项的更多信息,请参阅自定义 Web 应用初始化