新增 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()
      }
    }
  }
}

現在，您已將 Flutter 螢幕嵌入到您的 iOS 應用中。

以下示例展示了一個通用的 ViewController，其中包含一個連線到呈現 FlutterViewController 的 UIButton。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)
  }
}

現在，您已將 Flutter 螢幕嵌入到您的 iOS 應用中。

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

現在，您已將 Flutter 螢幕嵌入到您的 iOS 應用中。

作為上一個示例的替代方法，您可以讓 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 協議，以確保您的外掛收到必要的 API 回撥。否則，依賴於這些事件的外掛可能會出現未定義行為。

例如

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")

  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 入口點函式必須用以下方法進行註釋，以避免在編譯時被 árbol shake 掉。

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 例項啟動方式的方法。使用平臺通道，您可以隨意推送資料或以任何您想要的方式準備您的 Flutter 環境，然後再透過 FlutterViewController 呈現 Flutter UI。

此頁面內容有幫助嗎？

感謝你的反饋！

提供詳情

感謝你的反饋！請告訴我們如何改進。

提供詳情

除非另有說明，否則本網站上的文件反映了 Flutter 的最新穩定版本。頁面最後更新於 2025-09-05。檢視原始碼或報告問題。

將 Flutter 螢幕新增到 iOS 應用

啟動 FlutterEngine 和 FlutterViewController

建立 FlutterEngine

顯示帶有 FlutterEngine 的 FlutterViewController

或者 - 建立一個帶有隱式 FlutterEngine 的 FlutterViewController

使用 FlutterAppDelegate

建立 FlutterAppDelegate 子類

如果您無法直接繼承 FlutterAppDelegate

啟動選項

Dart 入口點

Dart 庫

Route

其他