flutter-embedding-native-views

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integrating Platform Views and Web Content

平台视图与Web内容集成

Platform Views Architecture

平台视图架构

Platform Views allow embedding native views (Android, iOS, macOS) directly into a Flutter application, enabling the application of transforms, clips, and opacity from Dart.

Platform Views支持将原生视图（Android、iOS、macOS）直接嵌入Flutter应用，能够通过Dart应用变换、裁剪和透明度效果。

Android Implementations (API 23+)

Android实现（API 23+）

Choose the appropriate implementation based on your performance and fidelity requirements:

Hybrid Composition: Renders Flutter content into a texture and uses
```
SurfaceFlinger
```
to compose both.
- Pros: Best performance and fidelity for Android views.
- Cons: Lowers overall application FPS. Certain Flutter widget transformations will not work.
Texture Layer (Texture Layer Hybrid Composition): Renders Platform Views into a texture. Flutter draws them via the texture and renders its own content directly into a Surface.
- Pros: Best performance for Flutter rendering. All transformations work correctly.
- Cons: Quick scrolling (e.g., WebViews) can be janky.
```
SurfaceView
```
  is problematic (breaks accessibility). Text magnifiers break unless Flutter is rendered into a
```
TextureView
```
  .

根据性能和保真度需求选择合适的实现方式：

Hybrid Composition：将Flutter内容渲染为纹理，使用
```
SurfaceFlinger
```
进行合成。
- 优点：对Android视图来说性能和保真度最佳。
- 缺点：会降低应用整体FPS。部分Flutter组件变换无法生效。
Texture Layer（Texture Layer Hybrid Composition）：将Platform Views渲染为纹理。Flutter通过该纹理绘制内容，并直接将自身内容渲染到Surface中。
- 优点：Flutter渲染性能最佳。所有变换均可正常工作。
- 缺点：快速滚动（如WebViews）时可能出现卡顿。
```
SurfaceView
```
  存在兼容性问题（会破坏无障碍功能）。除非Flutter渲染到
```
TextureView
```
  中，否则文本放大镜功能会失效。

iOS & macOS Implementations

iOS & macOS实现

iOS: Uses Hybrid Composition exclusively. The native
```
UIView
```
is appended to the view hierarchy.
- Limitations:
```
ShaderMask
```
  and
```
ColorFiltered
```
  widgets are not supported.
```
BackdropFilter
```
  has composition limitations.
macOS: Uses Hybrid Composition (
```
NSView
```
).
- Limitations: Not fully functional in current releases (e.g., gesture support is unavailable).

iOS：仅使用Hybrid Composition。原生
```
UIView
```
会被添加到视图层级中。
- 限制：不支持
```
ShaderMask
```
  和
```
ColorFiltered
```
  组件。
```
BackdropFilter
```
  存在合成限制。
macOS：使用Hybrid Composition（
```
NSView
```
）。
- 限制：当前版本中功能未完全实现（例如手势支持缺失）。

Performance Mitigation

性能优化

Mitigate performance drops during complex Dart animations by rendering a screenshot of the native view as a placeholder texture while the animation runs.

在复杂Dart动画运行期间，可将原生视图的截图作为占位纹理，以缓解性能下降问题。

Web Embedding Architecture

Web嵌入架构

Embed Flutter into existing web applications (Vanilla JS, React, Angular, etc.) using either Full Page mode or Embedded (Multi-view) mode.

Full Page Mode: Flutter takes over the entire browser window. Use an
```
iframe
```
if you need to constrain the Flutter app without modifying the Flutter bootstrap process.
Embedded Mode (Multi-view): Render Flutter into specific HTML elements (
```
div
```
s). Requires
```
multiViewEnabled: true
```
during engine initialization.
- Manage views from JavaScript using
```
app.addView()
```
  and
```
app.removeView()
```
  .
- In Dart, replace
```
runApp
```
  with
```
runWidget
```
  .
- Manage the dynamic list of views using
```
WidgetsBinding.instance.platformDispatcher.views
```
  and render them using
```
ViewCollection
```
  and
```
View
```
  widgets.

将Flutter嵌入现有Web应用（Vanilla JS、React、Angular等），支持全屏模式或嵌入（多视图）模式。

全屏模式：Flutter接管整个浏览器窗口。若需在不修改Flutter引导流程的情况下限制Flutter应用范围，可使用
```
iframe
```
。
嵌入模式（多视图）：将Flutter渲染到特定HTML元素（
```
div
```
）中。引擎初始化时需设置
```
multiViewEnabled: true
```
。
- 通过JavaScript使用
```
app.addView()
```
  和
```
app.removeView()
```
  管理视图。
- 在Dart中，用
```
runWidget
```
  替代
```
runApp
```
  。
- 使用
```
WidgetsBinding.instance.platformDispatcher.views
```
  管理动态视图列表，并通过
```
ViewCollection
```
  和
```
View
```
  组件进行渲染。

Workflow: Implementing Android Platform Views

工作流：实现Android平台视图

1. Dart Implementation

1. Dart实现

If using Hybrid Composition, use

PlatformViewLink

AndroidViewSurface

, and

PlatformViewsService.initSurfaceAndroidView

. If using Texture Layer, use the

AndroidView

widget.

若使用Hybrid Composition，需使用

PlatformViewLink

、

AndroidViewSurface

和

PlatformViewsService.initSurfaceAndroidView

。若使用Texture Layer，则使用

AndroidView

组件。

2. Native Implementation

2. 原生实现

Create a class implementing

io.flutter.plugin.platform.PlatformView

that returns your native

android.view.View

. Create a factory extending

PlatformViewFactory

to instantiate your view.

创建实现

io.flutter.plugin.platform.PlatformView

的类，返回你的原生

android.view.View

。创建继承自

PlatformViewFactory

的工厂类，用于实例化视图。

3. Registration

3. 注册

MainActivity.kt

(or plugin) using

flutterEngine.platformViewsController.registry.registerViewFactory

Note: If your native view uses
SurfaceView
or
SurfaceTexture
, manually call
invalidate
on the View or its parent when content changes, as they do not invalidate themselves automatically.

在

MainActivity.kt

（或插件）中，通过

flutterEngine.platformViewsController.registry.registerViewFactory

注册工厂类。

注意：若你的原生视图使用
SurfaceView
或
SurfaceTexture
，当内容变化时需手动调用View或其父视图的
invalidate
方法，因为它们不会自动触发失效。

Workflow: Implementing iOS Platform Views

工作流：实现iOS平台视图

Follow this sequential workflow to implement a Platform View on iOS.

Task Progress:

1. Implement the Dart widget using
```
UiKitView
```
.
2. Implement the native iOS View (
```
FlutterPlatformView
```
) and Factory (
```
FlutterPlatformViewFactory
```
).
3. Register the Platform View in
```
AppDelegate.swift
```
or the plugin registrar.
4. Run validator -> review composition limitations -> fix unsupported filters.

按照以下步骤在iOS上实现Platform View。

任务进度：

1. 使用
```
UiKitView
```
实现Dart组件。
2. 实现原生iOS View（
```
FlutterPlatformView
```
）与Factory（
```
FlutterPlatformViewFactory
```
）。
3. 在
```
AppDelegate.swift
```
或插件注册器中注册Platform View。
4. 运行验证器 -> 检查合成限制 -> 修复不支持的滤镜问题。

Workflow: Embedding Flutter in Web Applications

工作流：在Web应用中嵌入Flutter

Follow this sequential workflow to embed Flutter into an existing web DOM.

Task Progress:

1. Update
```
flutter_bootstrap.js
```
to enable multi-view.
2. Update
```
main.dart
```
to use
```
runWidget
```
and
```
ViewCollection
```
.
3. Implement JavaScript logic to add/remove host elements.
4. Run validator -> review view constraints -> fix CSS conflicts.

按照以下步骤将Flutter嵌入现有Web DOM中。

任务进度：

1. 更新
```
flutter_bootstrap.js
```
以启用多视图。
2. 更新
```
main.dart
```
以使用
```
runWidget
```
和
```
ViewCollection
```
。
3. 实现JavaScript逻辑以添加/移除宿主元素。
4. 运行验证器 -> 检查视图约束 -> 修复CSS冲突。

1. JavaScript Configuration

1. JavaScript配置

flutter_bootstrap.js

, initialize the engine with

multiViewEnabled: true

. Use the returned

app

object to add views:

app.addView({ hostElement: document.getElementById('my-div') })

在

flutter_bootstrap.js

中，初始化引擎时设置

multiViewEnabled: true

。使用返回的

app

对象添加视图：

app.addView({ hostElement: document.getElementById('my-div') })

。

2. Dart Configuration

2. Dart配置

Replace

runApp()

with

runWidget()

. Create a root widget that listens to

WidgetsBindingObserver.didChangeMetrics

. Map over

WidgetsBinding.instance.platformDispatcher.views

to create a

View

widget for each attached

FlutterView

, and wrap them all in a

ViewCollection

用

runWidget()

替代

runApp()

。创建根组件，监听

WidgetsBindingObserver.didChangeMetrics

。遍历

WidgetsBinding.instance.platformDispatcher.views

，为每个附加的

FlutterView

创建

View

组件，并将所有组件包裹在

ViewCollection

中。

Examples

示例

Example: Android Texture Layer (Dart)

示例：Android Texture Layer（Dart）

dart

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class NativeAndroidView extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    const String viewType = 'my_native_view';
    final Map<String, dynamic> creationParams = <String, dynamic>{};

    return AndroidView(
      viewType: viewType,
      layoutDirection: TextDirection.ltr,
      creationParams: creationParams,
      creationParamsCodec: const StandardMessageCodec(),
    );
  }
}

dart

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class NativeAndroidView extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    const String viewType = 'my_native_view';
    final Map<String, dynamic> creationParams = <String, dynamic>{};

    return AndroidView(
      viewType: viewType,
      layoutDirection: TextDirection.ltr,
      creationParams: creationParams,
      creationParamsCodec: const StandardMessageCodec(),
    );
  }
}

Example: Web Multi-View Initialization (JavaScript)

示例：Web多视图初始化（JavaScript）

javascript

_flutter.loader.load({
  onEntrypointLoaded: async function(engineInitializer) {
    let engine = await engineInitializer.initializeEngine({
      multiViewEnabled: true,
    });
    let app = await engine.runApp();
    
    // Add a view to a specific DOM element
    let viewId = app.addView({
      hostElement: document.querySelector('#flutter-host-container'),
      initialData: { customData: 'Hello from JS' }
    });
  }
});

javascript

_flutter.loader.load({
  onEntrypointLoaded: async function(engineInitializer) {
    let engine = await engineInitializer.initializeEngine({
      multiViewEnabled: true,
    });
    let app = await engine.runApp();
    
    // Add a view to a specific DOM element
    let viewId = app.addView({
      hostElement: document.querySelector('#flutter-host-container'),
      initialData: { customData: 'Hello from JS' }
    });
  }
});

Example: Web Multi-View Root Widget (Dart)

示例：Web多视图根组件（Dart）

dart

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

void main() {
  runWidget(MultiViewApp(viewBuilder: (context) => const MyEmbeddedWidget()));
}

class MultiViewApp extends StatefulWidget {
  final WidgetBuilder viewBuilder;
  const MultiViewApp({super.key, required this.viewBuilder});

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

class _MultiViewAppState extends State<MultiViewApp> with WidgetsBindingObserver {
  Map<Object, Widget> _views = {};

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _updateViews();
  }

  @override
  void didChangeMetrics() => _updateViews();

  void _updateViews() {
    final newViews = <Object, Widget>{};
    for (final FlutterView view in WidgetsBinding.instance.platformDispatcher.views) {
      newViews[view.viewId] = _views[view.viewId] ?? View(
        view: view,
        child: Builder(builder: widget.viewBuilder),
      );
    }
    setState(() => _views = newViews);
  }

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

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

dart

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

void main() {
  runWidget(MultiViewApp(viewBuilder: (context) => const MyEmbeddedWidget()));
}

class MultiViewApp extends StatefulWidget {
  final WidgetBuilder viewBuilder;
  const MultiViewApp({super.key, required this.viewBuilder});

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

class _MultiViewAppState extends State<MultiViewApp> with WidgetsBindingObserver {
  Map<Object, Widget> _views = {};

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _updateViews();
  }

  @override
  void didChangeMetrics() => _updateViews();

  void _updateViews() {
    final newViews = <Object, Widget>{};
    for (final FlutterView view in WidgetsBinding.instance.platformDispatcher.views) {
      newViews[view.viewId] = _views[view.viewId] ?? View(
        view: view,
        child: Builder(builder: widget.viewBuilder),
      );
    }
    setState(() => _views = newViews);
  }

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

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

flutter-embedding-native-views

Original

Translation

Integrating Platform Views and Web Content

平台视图与Web内容集成

Contents

目录

Platform Views Architecture

平台视图架构

Android Implementations (API 23+)

Android实现（API 23+）

iOS & macOS Implementations

iOS & macOS实现

Performance Mitigation

性能优化

Web Embedding Architecture

Web嵌入架构

Workflow: Implementing Android Platform Views

工作流：实现Android平台视图

1. Dart Implementation

1. Dart实现

2. Native Implementation

2. 原生实现

3. Registration

3. 注册

Workflow: Implementing iOS Platform Views

工作流：实现iOS平台视图

Workflow: Embedding Flutter in Web Applications

工作流：在Web应用中嵌入Flutter

1. JavaScript Configuration

1. JavaScript配置

2. Dart Configuration

2. Dart配置

Examples

示例

Example: Android Texture Layer (Dart)

示例：Android Texture Layer（Dart）

Example: Web Multi-View Initialization (JavaScript)

示例：Web多视图初始化（JavaScript）

Example: Web Multi-View Root Widget (Dart)

示例：Web多视图根组件（Dart）