添加 Flutter 屏幕 | Flutter 框架

本指南介绍了如何将单个 Flutter 屏幕添加到现有 iOS 应用中。

要从现有 iOS 应用启动 Flutter 屏幕，你需要启动一个 FlutterEngine 和一个 FlutterViewController。

FlutterEngine 的生命周期可能与 FlutterViewController 相同，也可能比 FlutterViewController 更长。

有关预热引擎的延迟和内存权衡的更多分析，请参阅加载序列和性能。

创建 FlutterEngine 的位置取决于你的宿主应用。

在这个示例中，我们在一个名为 FlutterDependencies 的 SwiftUI Observable 对象中创建了一个 FlutterEngine 对象。通过调用 run() 预热引擎，然后使用 environment() 视图修饰符将此对象注入到 ContentView 中。

MyApp.swift
swiftimport SwiftUI
import Flutter
// The following library connects plugins with iOS platform code to this app.
import FlutterPluginRegistrant

@Observable
class FlutterDependencies {
 let flutterEngine = FlutterEngine(name: "my flutter engine")
 init() {
   // Runs the default Dart entrypoint with a default Flutter route.
   flutterEngine.run()
   // Connects plugins with iOS platform code to this app.
   GeneratedPluginRegistrant.register(with: self.flutterEngine);
 }
}

@main
struct MyApp: App {
   // flutterDependencies will be injected through the view environment.
   @State var flutterDependencies = FlutterDependencies()
   var body: some Scene {
     WindowGroup {
       ContentView()
         .environment(flutterDependencies)
     }
   }
}

举例来说，我们演示了在应用程序启动时，在应用程序委托中创建一个 FlutterEngine，并将其作为属性公开。

AppDelegate.swift
swiftimport UIKit
import Flutter
// The following library connects plugins with iOS platform code to this app.
import FlutterPluginRegistrant

@UIApplicationMain
class AppDelegate: FlutterAppDelegate { // More on the FlutterAppDelegate.
  lazy var flutterEngine = FlutterEngine(name: "my flutter engine")

  override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Runs the default Dart entrypoint with a default Flutter route.
    flutterEngine.run();
    // Connects plugins with iOS platform code to this app.
    GeneratedPluginRegistrant.register(with: self.flutterEngine);
    return super.application(application, didFinishLaunchingWithOptions: launchOptions);
  }
}

以下示例演示了在应用程序启动时，在应用程序委托中创建一个 FlutterEngine，并将其作为属性公开。

AppDelegate.h
objc@import UIKit;
@import Flutter;

@interface AppDelegate : FlutterAppDelegate // More on the FlutterAppDelegate below.
@property (nonatomic,strong) FlutterEngine *flutterEngine;
@end

AppDelegate.m
objc// The following library connects plugins with iOS platform code to this app.
#import <flutterpluginregistrant generatedpluginregistrant.h="">

#import "AppDelegate.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary<uiapplicationlaunchoptionskey, id=""> *)launchOptions {
  self.flutterEngine = [[FlutterEngine alloc] initWithName:@"my flutter engine"];
  // Runs the default Dart entrypoint with a default Flutter route.
  [self.flutterEngine run];
  // Connects plugins with iOS platform code to this app.
  [GeneratedPluginRegistrant registerWithRegistry:self.flutterEngine];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

@end

</uiapplicationlaunchoptionskey,>

以下示例显示了一个通用 ContentView，其中包含一个连接到 Flutter 屏幕的 NavigationLink。首先，创建 FlutterViewControllerRepresentable 来表示 FlutterViewController。FlutterViewController 构造函数将预热的 FlutterEngine 作为参数，并通过视图环境注入。

ContentView.swift
swiftimport SwiftUI
import Flutter

struct FlutterViewControllerRepresentable: UIViewControllerRepresentable {
  // Flutter dependencies are passed in through the view environment.
  @Environment(FlutterDependencies.self) var flutterDependencies
  
  func makeUIViewController(context: Context) -> some UIViewController {
    return FlutterViewController(
      engine: flutterDependencies.flutterEngine,
      nibName: nil,
      bundle: nil)
  }
  
  func updateUIViewController(_ uiViewController: UIViewControllerType, context: Context) {}
}

struct ContentView: View {
  var body: some View {
    NavigationStack {
      NavigationLink("My Flutter Feature") {
        FlutterViewControllerRepresentable()
      }
    }
  }
}

现在，你的 iOS 应用中嵌入了一个 Flutter 屏幕。

以下示例展示了一个通用 ViewController，其中一个 UIButton 连接到显示 FlutterViewController。FlutterViewController 使用在 AppDelegate 中创建的 FlutterEngine 实例。

ViewController.swift
swiftimport UIKit
import Flutter

class ViewController: UIViewController {
  override func viewDidLoad() {
    super.viewDidLoad()

    // Make a button to call the showFlutter function when pressed.
    let button = UIButton(type:UIButton.ButtonType.custom)
    button.addTarget(self, action: #selector(showFlutter), for: .touchUpInside)
    button.setTitle("Show Flutter!", for: UIControl.State.normal)
    button.frame = CGRect(x: 80.0, y: 210.0, width: 160.0, height: 40.0)
    button.backgroundColor = UIColor.blue
    self.view.addSubview(button)
  }

  @objc func showFlutter() {
    let flutterEngine = (UIApplication.shared.delegate as! AppDelegate).flutterEngine
    let flutterViewController =
        FlutterViewController(engine: flutterEngine, nibName: nil, bundle: nil)
    present(flutterViewController, animated: true, completion: nil)
  }
}

现在，你的 iOS 应用中嵌入了一个 Flutter 屏幕。

ViewController.m
objc@import Flutter;
#import "AppDelegate.h"
#import "ViewController.h"

@implementation ViewController
- (void)viewDidLoad {
    [super viewDidLoad];

    // Make a button to call the showFlutter function when pressed.
    UIButton *button = [UIButton buttonWithType:UIButtonTypeCustom];
    [button addTarget:self
               action:@selector(showFlutter)
     forControlEvents:UIControlEventTouchUpInside];
    [button setTitle:@"Show Flutter!" forState:UIControlStateNormal];
    button.backgroundColor = UIColor.blueColor;
    button.frame = CGRectMake(80.0, 210.0, 160.0, 40.0);
    [self.view addSubview:button];
}

- (void)showFlutter {
    FlutterEngine *flutterEngine =
        ((AppDelegate *)UIApplication.sharedApplication.delegate).flutterEngine;
    FlutterViewController *flutterViewController =
        [[FlutterViewController alloc] initWithEngine:flutterEngine nibName:nil bundle:nil];
    [self presentViewController:flutterViewController animated:YES completion:nil];
}
@end

现在，你的 iOS 应用中嵌入了一个 Flutter 屏幕。

作为前一个示例的替代方案，你可以让 FlutterViewController 隐式创建自己的 FlutterEngine，而无需提前预热。

通常不建议这样做，因为按需创建 FlutterEngine 可能会在 FlutterViewController 显示和渲染其第一帧之间引入明显的延迟。然而，如果 Flutter 屏幕很少显示，没有好的启发式方法来确定何时启动 Dart VM，并且 Flutter 不需要跨视图控制器持久化状态时，这可能会很有用。

要让 FlutterViewController 在没有现有 FlutterEngine 的情况下显示，请省略 FlutterEngine 的构造，并创建不带引擎引用的 FlutterViewController。

ContentView.swift
swiftimport SwiftUI
import Flutter

struct FlutterViewControllerRepresentable: UIViewControllerRepresentable {
  func makeUIViewController(context: Context) -> some UIViewController {
    return FlutterViewController(
      project: nil,
      nibName: nil,
      bundle: nil)
  }
  
  func updateUIViewController(_ uiViewController: UIViewControllerType, context: Context) {}
}

struct ContentView: View {
  var body: some View {
    NavigationStack {
      NavigationLink("My Flutter Feature") {
        FlutterViewControllerRepresentable()
      }
    }
  }
}

ViewController.swift
swift// Existing code omitted.
func showFlutter() {
  let flutterViewController = FlutterViewController(project: nil, nibName: nil, bundle: nil)
  present(flutterViewController, animated: true, completion: nil)
}

ViewController.m
objc// Existing code omitted.
- (void)showFlutter {
  FlutterViewController *flutterViewController =
      [[FlutterViewController alloc] initWithProject:nil nibName:nil bundle:nil];
  [self presentViewController:flutterViewController animated:YES completion:nil];
}
@end

有关延迟和内存使用的更多探讨，请参阅加载序列和性能。

建议你的应用程序的 UIApplicationDelegate 子类化 FlutterAppDelegate，但这不是必需的。

FlutterAppDelegate 执行以下功能：

将诸如 openURL 等应用程序回调转发给诸如 local_auth 等插件。
在调试模式下，当手机屏幕锁定时保持 Flutter 连接打开。

在 UIKit 应用中创建 FlutterAppDelegate 的子类已在启动 FlutterEngine 和 FlutterViewController 部分中展示。在 SwiftUI 应用中，你可以创建 FlutterAppDelegate 的子类并使用 Observable() 宏进行注解，如下所示：

MyApp.swift
swiftimport SwiftUI
import Flutter
import FlutterPluginRegistrant

@Observable
class AppDelegate: FlutterAppDelegate {
  let flutterEngine = FlutterEngine(name: "my flutter engine")

  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
      // Runs the default Dart entrypoint with a default Flutter route.
      flutterEngine.run();
      // Used to connect plugins (only if you have plugins with iOS platform code).
      GeneratedPluginRegistrant.register(with: self.flutterEngine);
      return true;
    }
}

@main
struct MyApp: App {
  // Use this property wrapper to tell SwiftUI
  // it should use the AppDelegate class for the application delegate
  @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

  var body: some Scene {
      WindowGroup {
        ContentView()
      }
  }
}

然后，在你的视图中，可以通过视图环境访问 AppDelegate。

ContentView.swift
swiftimport SwiftUI
import Flutter

struct FlutterViewControllerRepresentable: UIViewControllerRepresentable {
  // Access the AppDelegate through the view environment.
  @Environment(AppDelegate.self) var appDelegate
  
  func makeUIViewController(context: Context) -> some UIViewController {
    return FlutterViewController(
      engine: appDelegate.flutterEngine,
      nibName: nil,
      bundle: nil)
  }
  
  func updateUIViewController(_ uiViewController: UIViewControllerType, context: Context) {}
}

struct ContentView: View {
  var body: some View {
    NavigationStack {
      NavigationLink("My Flutter Feature") {
        FlutterViewControllerRepresentable()
      }
    }
  }
}

如果你的应用程序委托无法直接将 FlutterAppDelegate 子类化，请让你的应用程序委托实现 FlutterAppLifeCycleProvider 协议，以确保你的插件接收必要的 Callback。否则，依赖这些事件的插件可能会出现未定义的行为。

例如

Swift
Objective-C

AppDelegate.swift
swiftimport Foundation
import Flutter

@Observable
class AppDelegate: UIResponder, UIApplicationDelegate, FlutterAppLifeCycleProvider {

  private let lifecycleDelegate = FlutterPluginAppLifeCycleDelegate()

  let flutterEngine = FlutterEngine(name: "my flutter engine")

  override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    flutterEngine.run()
    return lifecycleDelegate.application(application, didFinishLaunchingWithOptions: launchOptions ?? [:])
  }

  func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    lifecycleDelegate.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
  }

  func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    lifecycleDelegate.application(application, didFailToRegisterForRemoteNotificationsWithError: error)
  }

  func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    lifecycleDelegate.application(application, didReceiveRemoteNotification: userInfo, fetchCompletionHandler: completionHandler)
  }

  func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return lifecycleDelegate.application(app, open: url, options: options)
  }

  func application(_ application: UIApplication, handleOpen url: URL) -> Bool {
    return lifecycleDelegate.application(application, handleOpen: url)
  }

  func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    return lifecycleDelegate.application(application, open: url, sourceApplication: sourceApplication ?? "", annotation: annotation)
  }

  func application(_ application: UIApplication, performActionFor shortcutItem: UIApplicationShortcutItem, completionHandler: @escaping (Bool) -> Void) {
    lifecycleDelegate.application(application, performActionFor: shortcutItem, completionHandler: completionHandler)
  }

  func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
    lifecycleDelegate.application(application, handleEventsForBackgroundURLSession: identifier, completionHandler: completionHandler)
  }

  func application(_ application: UIApplication, performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    lifecycleDelegate.application(application, performFetchWithCompletionHandler: completionHandler)
  }

  func add(_ delegate: FlutterApplicationLifeCycleDelegate) {
    lifecycleDelegate.add(delegate)
  }
}

AppDelegate.h
objc@import Flutter;
@import UIKit;
@import FlutterPluginRegistrant;

@interface AppDelegate : UIResponder <uiapplicationdelegate, flutterapplifecycleprovider="">
@property (strong, nonatomic) UIWindow *window;
@property (nonatomic,strong) FlutterEngine *flutterEngine;
@end

实现应主要委托给 FlutterPluginAppLifeCycleDelegate

AppDelegate.m
objc@interface AppDelegate ()
@property (nonatomic, strong) FlutterPluginAppLifeCycleDelegate* lifeCycleDelegate;
@end

@implementation AppDelegate

- (instancetype)init {
    if (self = [super init]) {
        _lifeCycleDelegate = [[FlutterPluginAppLifeCycleDelegate alloc] init];
    }
    return self;
}

- (BOOL)application:(UIApplication*)application
didFinishLaunchingWithOptions:(NSDictionary<uiapplicationlaunchoptionskey, id="">*))launchOptions {
    self.flutterEngine = [[FlutterEngine alloc] initWithName:@"io.flutter" project:nil];
    [self.flutterEngine runWithEntrypoint:nil];
    [GeneratedPluginRegistrant registerWithRegistry:self.flutterEngine];
    return [_lifeCycleDelegate application:application didFinishLaunchingWithOptions:launchOptions];
}

// Returns the key window's rootViewController, if it's a FlutterViewController.
// Otherwise, returns nil.
- (FlutterViewController*)rootFlutterViewController {
    UIViewController* viewController = [UIApplication sharedApplication].keyWindow.rootViewController;
    if ([viewController isKindOfClass:[FlutterViewController class]]) {
        return (FlutterViewController*)viewController;
    }
    return nil;
}

- (void)application:(UIApplication*)application
didRegisterUserNotificationSettings:(UIUserNotificationSettings*)notificationSettings {
    [_lifeCycleDelegate application:application
didRegisterUserNotificationSettings:notificationSettings];
}

- (void)application:(UIApplication*)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken {
    [_lifeCycleDelegate application:application
didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

- (void)application:(UIApplication*)application
didReceiveRemoteNotification:(NSDictionary*)userInfo
fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
    [_lifeCycleDelegate application:application
       didReceiveRemoteNotification:userInfo
             fetchCompletionHandler:completionHandler];
}

- (BOOL)application:(UIApplication*)application
            openURL:(NSURL*)url
            options:(NSDictionary<uiapplicationopenurloptionskey, id="">*)options {
    return [_lifeCycleDelegate application:application openURL:url options:options];
}

- (BOOL)application:(UIApplication*)application handleOpenURL:(NSURL*)url {
    return [_lifeCycleDelegate application:application handleOpenURL:url];
}

- (BOOL)application:(UIApplication*)application
            openURL:(NSURL*)url
  sourceApplication:(NSString*)sourceApplication
         annotation:(id)annotation {
    return [_lifeCycleDelegate application:application
                                   openURL:url
                         sourceApplication:sourceApplication
                                annotation:annotation];
}

- (void)application:(UIApplication*)application
performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
  completionHandler:(void (^)(BOOL succeeded))completionHandler {
    [_lifeCycleDelegate application:application
       performActionForShortcutItem:shortcutItem
                  completionHandler:completionHandler];
}

- (void)application:(UIApplication*)application
handleEventsForBackgroundURLSession:(nonnull NSString*)identifier
  completionHandler:(nonnull void (^)(void))completionHandler {
    [_lifeCycleDelegate application:application
handleEventsForBackgroundURLSession:identifier
                  completionHandler:completionHandler];
}

- (void)application:(UIApplication*)application
performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult result))completionHandler {
    [_lifeCycleDelegate application:application performFetchWithCompletionHandler:completionHandler];
}

- (void)addApplicationLifeCycleDelegate:(NSObject<flutterplugin>*)delegate {
    [_lifeCycleDelegate addDelegate:delegate];
}
@end

</uiapplicationopenurloptionskey,></uiapplicationlaunchoptionskey,></uiapplicationdelegate,>

这些示例演示了使用默认启动设置运行 Flutter。

为了自定义你的 Flutter 运行时，你还可以指定 Dart 入口点、库和路由。

默认情况下，在 FlutterEngine 上调用 run 会运行你的 lib/main.dart 文件中的 main() Dart 函数。

你还可以使用 runWithEntrypoint 并指定一个不同的 Dart 函数的 NSString 来运行不同的入口点函数。

注意

除了 main() 之外的 Dart 入口点函数必须使用以下内容进行注解，以避免在编译时被 tree-shaken 掉：

dart@pragma('vm:entry-point')
void myOtherEntrypoint() { ... };

除了指定 Dart 函数，你还可以在特定文件中指定入口点函数。

例如，以下代码将运行 lib/other_file.dart 中的 myOtherEntrypoint()，而不是 lib/main.dart 中的 main()。

Swift
Objective-C

swiftflutterEngine.run(withEntrypoint: "myOtherEntrypoint", libraryURI: "other_file.dart")

objc[flutterEngine runWithEntrypoint:@"myOtherEntrypoint" libraryURI:@"other_file.dart"];

从 Flutter 1.22 版本开始，在构造 FlutterEngine 或 FlutterViewController 时，可以为你的 Flutter WidgetsApp 设置初始路由。

Swift
Objective-C

swiftlet flutterEngine = FlutterEngine()
// FlutterDefaultDartEntrypoint is the same as nil, which will run main().
engine.run(
  withEntrypoint: "main", initialRoute: "/onboarding")

objcFlutterEngine *flutterEngine = [[FlutterEngine alloc] init];
// FlutterDefaultDartEntrypoint is the same as nil, which will run main().
[flutterEngine runWithEntrypoint:FlutterDefaultDartEntrypoint
                    initialRoute:@"/onboarding"];

此代码将你的 dart:ui 的 PlatformDispatcher.defaultRouteName 设置为 "/onboarding" 而不是 "/"。

或者，可以直接构造 FlutterViewController，而无需预热 FlutterEngine。

Swift
Objective-C

swiftlet flutterViewController = FlutterViewController(
      project: nil, initialRoute: "/onboarding", nibName: nil, bundle: nil)

objcFlutterViewController* flutterViewController =
      [[FlutterViewController alloc] initWithProject:nil
                                        initialRoute:@"/onboarding"
                                             nibName:nil
                                              bundle:nil];

有关 Flutter 路由的更多信息，请参阅导航和路由。

前面的示例仅说明了几种自定义 Flutter 实例启动方式的方法。使用平台通道，你可以在使用 FlutterViewController 显示 Flutter UI 之前，自由地推送数据或以任何你喜欢的方式准备 Flutter 环境。

此页面内容有帮助吗？

感谢你的反馈！

提供详情

感谢你的反馈！请告诉我们如何改进。

提供详情

除非另有说明，本网站上的文档反映了 Flutter 的最新稳定版本。页面最后更新日期：2024-11-20。查看源代码或报告问题。

将 Flutter 屏幕添加到 iOS 应用

启动 FlutterEngine 和 FlutterViewController

创建 FlutterEngine

使用 FlutterEngine 显示 FlutterViewController

或者 - 创建带有隐式 FlutterEngine 的 FlutterViewController

使用 FlutterAppDelegate

创建 FlutterAppDelegate 子类

如果无法直接将 FlutterAppDelegate 子类化

启动选项

Dart 入口点

Dart 库

路由

其他