將 Flutter 應用程式整合至您的 macOS 專案

瞭解如何將 Flutter 應用程式整合至您現有的 macOS 專案。

Flutter UI 元件 (Widget) 可以透過 Swift 套件逐步新增至您現有的 macOS 應用程式中。

Flutter 3.44 或更新版本
Xcode 15.0 或更新版本

若您先前已使用嵌入式框架將 Flutter 整合至 macOS 應用程式，在依照以下 Swift Package Manager 指示操作之前，必須先移除該整合。

展開以查看從嵌入式框架整合方式遷移的指示

若您的應用程式先前使用由 flutter build macos-framework 指令產生的框架進行整合，必須先從 Xcode 專案中移除這些框架。

前往您目標的 General 分頁，在 Frameworks, Libraries, and Embedded Content 下移除所有與 Flutter 相關的框架和函式庫。
這包括 App.xcframework、FlutterMacOS.xcframework、 FlutterPluginRegistrant.xcframework，以及任何 Flutter 插件的 xcframework 檔案。

從 Podfile 中移除 Flutter pod

MyApp/Podfile

ruby

pod 'FlutterMacOS', :podspec => '/path/to/MyApp/Flutter/[build mode]/FlutterMacOS.podspec'

執行 pod install。

本指南假設您現有的 macOS 應用程式和 Flutter 應用程式位於相鄰的目錄中。若您的目錄結構不同，需要相應調整範例中的相對路徑。

Note

若是首次整合，請執行以下指令建立新的 Flutter 應用程式：

flutter create my_flutter_app

範例目錄結構如下所示：

my_flutter_app/
- macos/
- lib/
  - main.dart
MyNativeApp/
- MyNativeApp.xcodeproj/

建置 FlutterNativeIntegration Swift 套件
在您的 Flutter 應用程式或模組中，執行以下指令：
```
flutter build swift-package --platform macos
```
此指令會產生以下目錄：
- my_flutter_app/build/macos/SwiftPackages/
  - FlutterNativeIntegration/(一個 Swift 套件)
  - Scripts/(腳本及其他所需檔案的目錄)
您可以選擇使用 --output 旗標來變更此輸出的位置。
將 FlutterNativeIntegration 新增至您的 Xcode 專案
1. 在 Project navigator 中，右鍵點擊您的專案並選擇 Add Files to "MyNativeApp"...
2. 導覽至並選取產生的 FlutterNativeIntegration Swift 套件，然後點擊 Add。
3. 選擇 Reference files in place 並點擊 Finish。
4. 在 File inspector 中，確認 Location 為 Relative to Project。若不是，您需要將 Flutter 輸出目錄移至與原生應用程式相鄰的目錄。
  Xcode File inspector 中顯示的 FlutterNativeIntegration 相對位置。
5. 前往您目標的 General 分頁，在 Frameworks, Libraries, and Embedded Content 下新增 FlutterNativeIntegration。
  Frameworks, Libraries, and Embedded Content 下的 FlutterNativeIntegration。
新增建置設定
1. 在 Build Settings 分頁中，設定 Flutter 應用程式 Swift 套件輸出目錄的位置：
```
FLUTTER_SWIFT_PACKAGE_OUTPUT=$SRCROOT/../my_flutter_app/build/macos/SwiftPackages
```
2. 針對自訂設定，設定 Flutter 建置模式。
  Flutter 支援三種建置模式：Debug、Profile 和 Release。建置模式透過 CONFIGURATION 的值來決定。若您的設定名稱與這些名稱不符，可以將 FLUTTER_BUILD_MODE 建置設定設為其中一個值。
  在 Build Settings 下為自訂設定設定 FLUTTER_BUILD_MODE。
3. 僅針對 Debug 設定，設定以下建置設定：
```
ENABLE_APP_SANDBOX=YES
ENABLE_INCOMING_NETWORK_CONNECTIONS=YES
RUNTIME_EXCEPTION_ALLOW_JIT=YES
```
  僅針對 Debug 設定，在目標的 Build Settings 中將 Allow JIT (RUNTIME_EXCEPTION_ALLOW_JIT) 設為 YES。
4. （可選）允許 Xcode 重新建置您的 Flutter 應用程式。
  在目標中新增以下建置設定，讓 Xcode 在其建置過程中重新建置您的 Flutter 應用程式。這可讓您在修改 Flutter 應用程式時，無需重新執行 flutter build swift-package。這需要機器上已安裝 Flutter。
```
FLUTTER_APPLICATION_PATH=$SRCROOT/../my_flutter_app
ENABLE_USER_SCRIPT_SANDBOXING=NO
```
  Tip
  這只會重新建置 Flutter 應用程式的程式碼。若您新增了新的相依套件，仍需重新執行 flutter build swift-package。
在 Scheme 中新增 Pre-action Run Script
1. 開啟 Product > Scheme > Edit Scheme... > Build（左側邊欄）> Pre-action > + > New Run Script Action
2. 在 Provide build settings from 下拉選單中選擇您的專案。
3. 將腳本設定為以下內容：
```
/bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh prebuild
```
Scheme 編輯器中的 Pre-action Run Script。
在目標中新增新的 Run Script 建置階段
1. 前往您目標的 Build Phases > + > New Run Script Phase
2. 將腳本設定為以下內容：
```
/bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh assemble
```
3. 取消勾選 Based on dependency analysis
4. 在 Input File Lists 中新增以下內容：
```
$(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/FlutterAssembleInputs.xcfilelist
```
Build Phases 下的新 Run Script Build Phase。