将 Flutter 应用集成到 macOS 项目

了解如何将 Flutter 应用集成到你现有的 macOS 项目中。

可使用 Swift package 将 Flutter UI 组件逐步添加到你现有的 macOS 应用中。

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

若你已使用嵌入 framework 将 Flutter 集成到 macOS 应用，须先移除该集成，再按下方 Swift Package Manager 说明操作。

展开查看从嵌入 framework 集成迁移的说明

若应用此前通过 flutter build macos-framework 命令生成的 framework 集成，须先从 Xcode 项目中移除这些 framework。

进入 target 的 General 标签页，在 Frameworks, Libraries, and Embedded Content 下移除所有与 Flutter 相关的 framework 与库。
包括 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 应用位于同级目录。若目录结构不同，须相应调整示例中的相对路径。

提示

若首次集成，运行以下命令创建新的 Flutter 应用：

flutter create my_flutter_app

示例目录结构如下：

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

构建 FlutterNativeIntegration Swift package
在 Flutter 应用或模块中运行以下命令：
```
flutter build swift-package --platform macos
```
将生成以下目录：
- my_flutter_app/build/macos/SwiftPackages/
  - FlutterNativeIntegration/(A Swift package)
  - Scripts/(Directory of scripts and other files needed)
你可使用 --output 标志可选地更改输出位置。
将 FlutterNativeIntegration 添加到 Xcode 项目
1. 在 Project navigator 中右键项目，选择 Add Files to "MyNativeApp"...
2. 找到并选择生成的 FlutterNativeIntegration Swift package，点击 Add。
3. 选择 Reference files in place，点击 Finish。
4. 在 File inspector 中确认 Location 为 Relative to Project。若不是，须将 Flutter 输出目录移至与原生应用同级的目录。
  Relative location of FlutterNativeIntegration shown in Xcode's File inspector.
5. 进入 target 的 General 标签页，在 Frameworks, Libraries, and Embedded Content 下添加 FlutterNativeIntegration。
  FlutterNativeIntegration under Frameworks, Libraries, and Embedded Content.
添加构建设置
1. 在 Build Settings 标签页中设置 Flutter 应用 Swift package 输出目录位置：
```
FLUTTER_SWIFT_PACKAGE_OUTPUT=$SRCROOT/../my_flutter_app/build/macos/SwiftPackages
```
2. 对于自定义配置，设置 Flutter 构建模式。
  Flutter 支持三种构建模式：Debug、Profile 与 Release。构建模式由 CONFIGURATION 值决定。若配置不匹配其中任一，可将 FLUTTER_BUILD_MODE 构建设置设为这些值之一。
  Setting FLUTTER_BUILD_MODE for custom configurations under Build Settings.
3. 仅对 Debug 配置设置以下构建设置：
```
ENABLE_APP_SANDBOX=YES
ENABLE_INCOMING_NETWORK_CONNECTIONS=YES
RUNTIME_EXCEPTION_ALLOW_JIT=YES
```
  Set Allow JIT (RUNTIME_EXCEPTION_ALLOW_JIT) to YES in the target's Build Settings for Debug configurations only.
4. （可选）允许 Xcode 重新构建 Flutter 应用。
  向 target 添加以下构建设置，使 Xcode 在构建过程中重新构建 Flutter 应用。这样修改 Flutter 应用后无需重新运行 flutter build swift-package。这要求机器上已安装 Flutter。
```
FLUTTER_APPLICATION_PATH=$SRCROOT/../my_flutter_app
ENABLE_USER_SCRIPT_SANDBOXING=NO
```
  小提示
  这仅重新构建 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
```
Pre-action Run Script in scheme editor.
向 target 添加新的 Run Script 构建阶段
1. 进入 target 的 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
```
New Run Script Build Phase under Build Phases.