description bug_report

使用平台视图在 Flutter 应用中托管原生 Android 视图

内容

在 Dart 方面
在平台方面
性能

平台视图允许你在 Flutter 应用中嵌入原生视图，以便你可以从 Dart 对原生视图应用变换、剪辑和不透明度。

例如，这允许你直接在 Flutter 应用中使用 Android SDK 中的原生 Google 地图。

Flutter 支持两种模式：混合合成和虚拟显示。

使用哪种模式取决于用例。让我们来看看

混合合成将原生 android.view.View 附加到视图层次结构。因此，键盘处理和辅助功能开箱即用。在 Android 10 之前，此模式可能会显著降低 Flutter UI 的帧吞吐量 (FPS)。有关更多背景信息，请参阅性能。
虚拟显示将 android.view.View 实例渲染到纹理，因此它不会嵌入到 Android Activity 的视图层次结构中。某些平台交互（例如键盘处理和辅助功能）可能无法使用。

要在 Android 上创建平台视图，请使用以下步骤

在 Dart 方面

在 Dart 方面，创建一个 Widget 并添加以下构建实现之一。

混合合成

在你的 Dart 文件中，例如 native_view_example.dart，使用以下说明

添加以下导入

import 'package:flutter/foundation.dart';
import 'package:flutter/gestures.dart';
import 'package:flutter/material.dart';
import 'package:flutter/rendering.dart';
import 'package:flutter/services.dart';

实现一个 build() 方法

Widget build(BuildContext context) {
  // This is used in the platform side to register the view.
  const String viewType = '<platform-view-type>';
  // Pass parameters to the platform side.
  const Map<String, dynamic> creationParams = <String, dynamic>{};

  return PlatformViewLink(
    viewType: viewType,
    surfaceFactory: (context, controller) {
      return AndroidViewSurface(
        controller: controller as AndroidViewController,
        gestureRecognizers: const <Factory<OneSequenceGestureRecognizer>>{},
        hitTestBehavior: PlatformViewHitTestBehavior.opaque,
      );
    },
    onCreatePlatformView: (params) {
      return PlatformViewsService.initSurfaceAndroidView(
        id: params.id,
        viewType: viewType,
        layoutDirection: TextDirection.ltr,
        creationParams: creationParams,
        creationParamsCodec: const StandardMessageCodec(),
        onFocus: () {
          params.onFocusChanged(true);
        },
      )
        ..addOnPlatformViewCreatedListener(params.onPlatformViewCreated)
        ..create();
    },
  );
}

更多信息，请参阅以下 API 文档

虚拟显示

在你的 Dart 文件中，例如 native_view_example.dart，使用以下说明

添加以下导入

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

实现一个 build() 方法

Widget build(BuildContext context) {
  // This is used in the platform side to register the view.
  const String viewType = '<platform-view-type>';
  // Pass parameters to the platform side.
  final Map<String, dynamic> creationParams = <String, dynamic>{};

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

更多信息，请参阅以下 API 文档

AndroidView

在平台端

在平台端，在 Java 或 Kotlin 中使用标准 io.flutter.plugin.platform 包

Kotlin
Java

在你的原生代码中，实现以下内容

扩展 io.flutter.plugin.platform.PlatformView 以提供对 android.view.View 的引用（例如，NativeView.kt）

package dev.flutter.example

import android.content.Context
import android.graphics.Color
import android.view.View
import android.widget.TextView
import io.flutter.plugin.platform.PlatformView

internal class NativeView(context: Context, id: Int, creationParams: Map<String?, Any?>?) : PlatformView {
    private val textView: TextView

    override fun getView(): View {
        return textView
    }

    override fun dispose() {}

    init {
        textView = TextView(context)
        textView.textSize = 72f
        textView.setBackgroundColor(Color.rgb(255, 255, 255))
        textView.text = "Rendered on a native Android view (id: $id)"
    }
}

创建一个工厂类，用于创建前面创建的 NativeView 的实例（例如，NativeViewFactory.kt）

package dev.flutter.example

import android.content.Context
import io.flutter.plugin.common.StandardMessageCodec
import io.flutter.plugin.platform.PlatformView
import io.flutter.plugin.platform.PlatformViewFactory

class NativeViewFactory : PlatformViewFactory(StandardMessageCodec.INSTANCE) {
    override fun create(context: Context, viewId: Int, args: Any?): PlatformView {
        val creationParams = args as Map<String?, Any?>?
        return NativeView(context, viewId, creationParams)
    }
}

最后，注册平台视图。你可以在应用或插件中执行此操作。

对于应用注册，修改应用的主活动（例如，MainActivity.kt）

package dev.flutter.example

import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine

class MainActivity : FlutterActivity() {
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)
        flutterEngine
                .platformViewsController
                .registry
                .registerViewFactory("<platform-view-type>", 
                                      NativeViewFactory())
    }
}

对于插件注册，修改插件的主类（例如，PlatformViewPlugin.kt）

package dev.flutter.plugin.example

import io.flutter.embedding.engine.plugins.FlutterPlugin
import io.flutter.embedding.engine.plugins.FlutterPlugin.FlutterPluginBinding

class PlatformViewPlugin : FlutterPlugin {
    override fun onAttachedToEngine(binding: FlutterPluginBinding) {
        binding
                .platformViewRegistry
                .registerViewFactory("<platform-view-type>", NativeViewFactory())
    }

    override fun onDetachedFromEngine(binding: FlutterPluginBinding) {}
}

在你的原生代码中，实现以下内容

扩展 io.flutter.plugin.platform.PlatformView 以提供对 android.view.View 的引用（例如，NativeView.java）

package dev.flutter.example;

import android.content.Context;
import android.graphics.Color;
import android.view.View;
import android.widget.TextView;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import io.flutter.plugin.platform.PlatformView;
import java.util.Map;

class NativeView implements PlatformView {
   @NonNull private final TextView textView;

    NativeView(@NonNull Context context, int id, @Nullable Map<String, Object> creationParams) {
        textView = new TextView(context);
        textView.setTextSize(72);
        textView.setBackgroundColor(Color.rgb(255, 255, 255));
        textView.setText("Rendered on a native Android view (id: " + id + ")");
    }

    @NonNull
    @Override
    public View getView() {
        return textView;
    }

    @Override
    public void dispose() {}
}

创建一个工厂类，用于创建前面创建的 NativeView 的实例（例如，NativeViewFactory.java）

package dev.flutter.example;

import android.content.Context;
import androidx.annotation.Nullable;
import androidx.annotation.NonNull;
import io.flutter.plugin.common.StandardMessageCodec;
import io.flutter.plugin.platform.PlatformView;
import io.flutter.plugin.platform.PlatformViewFactory;
import java.util.Map;

class NativeViewFactory extends PlatformViewFactory {

  NativeViewFactory() {
    super(StandardMessageCodec.INSTANCE);
  }

  @NonNull
  @Override
  public PlatformView create(@NonNull Context context, int id, @Nullable Object args) {
    final Map<String, Object> creationParams = (Map<String, Object>) args;
    return new NativeView(context, id, creationParams);
  }
}

最后，注册平台视图。你可以在应用或插件中执行此操作。

对于应用注册，修改应用的主活动（例如，MainActivity.java）

package dev.flutter.example;

import androidx.annotation.NonNull;
import io.flutter.embedding.android.FlutterActivity;
import io.flutter.embedding.engine.FlutterEngine;

public class MainActivity extends FlutterActivity {
    @Override
    public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
        flutterEngine
            .getPlatformViewsController()
            .getRegistry()
            .registerViewFactory("<platform-view-type>", new NativeViewFactory());
    }
}

对于插件注册，修改插件的主文件（例如，PlatformViewPlugin.java）

package dev.flutter.plugin.example;

import androidx.annotation.NonNull;
import io.flutter.embedding.engine.plugins.FlutterPlugin;

public class PlatformViewPlugin implements FlutterPlugin {
  @Override
  public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
    binding
        .getPlatformViewRegistry()
        .registerViewFactory("<platform-view-type>", new NativeViewFactory());
  }

  @Override
  public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {}
}

更多信息，请参阅以下 API 文档

最后，修改您的 build.gradle 文件，以要求最低的 Android SDK 版本之一

android {
    defaultConfig {
        minSdkVersion 19 // if using hybrid composition
        minSdkVersion 20 // if using virtual display.
    }
}

手动视图失效

某些 Android 视图在内容更改时不会失效。一些示例视图包括 SurfaceView 和 SurfaceTexture。当您的平台视图包含这些视图时，您需要在绘制到这些视图之后（或更具体地说：在交换链翻转之后）手动使视图失效。通过在视图或其父视图之一上调用 invalidate 来完成手动视图失效。

性能

Flutter 中的平台视图会带来性能权衡。

例如，在典型的 Flutter 应用中，Flutter UI 在一个专用的光栅线程上构成。这使得 Flutter 应用可以快速运行，因为主平台线程很少被阻塞。

当平台视图使用混合合成呈现时，Flutter UI 由平台线程构成，该线程与处理操作系统或插件消息等其他任务竞争。

在 Android 10 之前，混合合成将每个 Flutter 帧从图形内存复制到主内存中，然后将其复制回 GPU 纹理。由于此复制是逐帧发生的，因此整个 Flutter UI 的性能可能会受到影响。在 Android 10 或更高版本中，图形内存仅复制一次。

另一方面，虚拟显示器使原生视图的每个像素流经额外的中间图形缓冲区，这会消耗图形内存和绘图性能。

对于复杂的情况，有一些技术可用于缓解这些问题。

例如，您可以在 Dart 中发生动画时使用占位符纹理。换句话说，如果在渲染平台视图时动画很慢，那么可以考虑对原生视图进行屏幕截图并将其作为纹理进行渲染。

有关更多信息，请参阅