将 Flutter 应用集成到 macOS 项目

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

• Flutter 3.44 or later

• Xcode 15.0 or later

• Flutter 3.44 或更高版本

• Xcode 15.0 或更高版本

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

本指南假定现有 macOS 应用与 Flutter 应用位于同级目录。若目录结构不同，须相应调整示例中的相对路径。

示例目录结构如下：

1. Build the FlutterNativeIntegration Swift package

   Within your Flutter application or module, run the following command:

   flutter build swift-package --platform macos
   

   content_copy

   This generates the following directories:

   • my_flutter_app/build/macos/SwiftPackages/

     • FlutterNativeIntegration/(A Swift package)
     • Scripts/(Directory of scripts and other files needed)

   You can optionally change the location of this output with the --output flag.

2. 构建 FlutterNativeIntegration Swift package

   在 Flutter 应用或模块中运行以下命令：

   flutter build swift-package --platform macos
   

   content_copy

   将生成以下目录：

   • my_flutter_app/build/macos/SwiftPackages/

     • FlutterNativeIntegration/(A Swift package)
     • Scripts/(Directory of scripts and other files needed)

   可使用 --output 标志可选地更改输出位置。

3. Add FlutterNativeIntegration to your Xcode project

   1. In the Project navigator, right click on your project and select Add Files to "MyNativeApp"...

   2. Navigate to and select the generated FlutterNativeIntegration Swift package and click Add.

   3. Select Reference files in place and click Finish.

   4. In the File inspector, verify the Location is Relative to Project. If it is not, you'll need to move the Flutter output directory to be a sibling directory of your native app.

      

   5. Navigate to your target's General tab and add FlutterNativeIntegration under Frameworks, Libraries, and Embedded Content.

4. 将 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 输出目录移至与原生应用同级的目录。

      

   5. 进入 target 的 General 标签页，在 Frameworks, Libraries, and Embedded Content 下添加 FlutterNativeIntegration。

5. Add build settings

   1. In the Build Settings tab, set the location of the Flutter app's Swift package output directory:

      FLUTTER_SWIFT_PACKAGE_OUTPUT=$SRCROOT/../my_flutter_app/build/macos/SwiftPackages
      

      content_copy

   2. For custom configurations, set the Flutter build mode.

      Flutter supports three build modes: Debug, Profile, and Release. The build mode is determined using the CONFIGURATION value. If your configuration does not match one of these, you can set the FLUTTER_BUILD_MODE build setting to one of these values.

      

   3. For Debug configurations only, set the following build settings:

      ENABLE_APP_SANDBOX=YES
      ENABLE_INCOMING_NETWORK_CONNECTIONS=YES
      RUNTIME_EXCEPTION_ALLOW_JIT=YES
      

      content_copy
      

   4. (Optional) Allow Xcode to re-build your Flutter app.

      Add the following build settings to your target to allow Xcode to re-build your Flutter app as part of its build. This allows you to make changes to your Flutter application without needing to re-run flutter build swift-package. This requires a Flutter installation on the machine.

      FLUTTER_APPLICATION_PATH=$SRCROOT/../my_flutter_app
      ENABLE_USER_SCRIPT_SANDBOXING=NO
      

      content_copy

6. 添加构建设置

   1. 在 Build Settings 标签页中设置 Flutter 应用 Swift package 输出目录位置：

      FLUTTER_SWIFT_PACKAGE_OUTPUT=$SRCROOT/../my_flutter_app/build/macos/SwiftPackages
      

      content_copy

   2. 对于自定义配置，设置 Flutter 构建模式。

      Flutter 支持三种 构建模式：Debug、Profile 与 Release。构建模式由 CONFIGURATION 值决定。若配置不匹配其中任一，可将 FLUTTER_BUILD_MODE 构建设置设为这些值之一。

      

   3. 仅对 Debug 配置设置以下构建设置：

      ENABLE_APP_SANDBOX=YES
      ENABLE_INCOMING_NETWORK_CONNECTIONS=YES
      RUNTIME_EXCEPTION_ALLOW_JIT=YES
      

      content_copy
      

   4. （可选）允许 Xcode 重新构建 Flutter 应用。

      向 target 添加以下构建设置，使 Xcode 在构建过程中重新构建 Flutter 应用。这样修改 Flutter 应用后无需重新运行 flutter build swift-package。这要求机器上已安装 Flutter。

      FLUTTER_APPLICATION_PATH=$SRCROOT/../my_flutter_app
      ENABLE_USER_SCRIPT_SANDBOXING=NO
      

      content_copy

7. Add Pre-action Run Script to Scheme

   1. Open Product > Scheme > Edit Scheme... > Build (in left side bar) > Pre-action > + > New Run Script Action

   2. Select your project in the Provide build settings from dropdown.

   3. Set the script to the following:

      /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh prebuild
      

      content_copy
   

8. 向 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
      

      content_copy
   

9. Add new run script build phase to your target

   1. Navigate to your target's Build Phases > + > New Run Script Phase

   2. Set the script to the following:

      /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh assemble
      

      content_copy

   3. Uncheck Based on dependency analysis

   4. Add the following to Input File Lists:

      $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/FlutterAssembleInputs.xcfilelist
      

      content_copy
   

10. 向 target 添加新的 Run Script 构建阶段

    1. 进入 target 的 Build Phases > + > New Run Script Phase

    2. 将脚本设置为：

       /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh assemble
       

       content_copy

    3. 取消勾选 Based on dependency analysis

    4. 在 Input File Lists 中添加：

       $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/FlutterAssembleInputs.xcfilelist
       

       content_copy
    

你现在可以 向现有 macOS 应用添加 Flutter 屏幕。