Objective-C 和 Swift 互操作性，使用 package:ffigen

在 macOS 或 iOS 上运行的 Dart 移动、命令行和服务器应用程序，在 Dart Native 平台上，可以使用 dart:ffi 和 package:ffigen 调用 Objective-C 和 Swift API。

dart:ffi 使 Dart 代码能够与原生 C API 交互。Objective-C 基于 C 并与 C 兼容，因此只使用 dart:ffi 就可以与 Objective-C API 交互。但是，这样做涉及大量的样板代码，因此您可以使用 package:ffigen 自动为给定的 Objective-C API 生成 Dart FFI 绑定。要了解更多关于 FFI 以及直接与 C 代码接口的信息，请参阅C 互操作指南。

您可以为 Swift API 生成 Objective-C 头文件，从而使 dart:ffi 和 package:ffigen 能够与 Swift 交互。

本指南将引导您完成一个示例，该示例使用 package:ffigen 为 AVAudioPlayer 生成绑定。此 API 需要至少 macOS SDK 10.7，因此请检查您的版本并在必要时更新 Xcode。

xcodebuild -showsdks

生成绑定以包装 Objective-C API 与包装 C API 类似。将 package:ffigen 指向描述 API 的头文件，然后使用 dart:ffi 加载库。

package:ffigen 使用 LLVM 解析 Objective-C 头文件，所以您需要首先安装它。更多详情请参阅 ffigen README 中的安装 LLVM。

首先，添加 package:ffigen 作为开发依赖项

dart pub add --dev ffigen

然后，配置 ffigen 为包含 API 的 Objective-C 头文件生成绑定。ffigen 配置选项放在您的 pubspec.yaml 文件中，位于顶层 ffigen 条目下。或者，您可以将 ffigen 配置放在单独的 .yaml 文件中。

ffigen:
  name: AVFAudio
  description: Bindings for AVFAudio.
  language: objc
  output: 'avf_audio_bindings.dart'
  headers:
    entry-points:
      - '/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks/AVFAudio.framework/Headers/AVAudioPlayer.h'

name 是将要生成的原生库包装器类的名称，description 将用于该类的文档中。output 是 ffigen 将创建的 Dart 文件的路径。入口点是包含 API 的头文件。在此示例中，它是内部的 AVAudioPlayer.h 头文件。

如果您查看示例配置，还会看到另一个重要内容：exclude 和 include 选项。默认情况下，ffigen 会为它在头文件中找到的所有内容以及这些绑定在其他头文件中依赖的所有内容生成绑定。大多数 Objective-C 库都依赖 Apple 的内部库，这些库非常庞大。如果生成绑定时没有任何过滤器，结果文件可能会有数百万行长。为了解决这个问题，ffigen 配置提供了字段，使您能够过滤掉所有您不感兴趣的函数、结构体、枚举等。对于这个示例，我们只对 AVAudioPlayer 感兴趣，因此您可以排除所有其他内容。

  exclude-all-by-default: true
  objc-interfaces:
    include:
      - 'AVAudioPlayer'

由于 AVAudioPlayer 被这样明确地包含，ffigen 会排除所有其他接口。exclude-all-by-default 标志告诉 ffigen 排除其他所有内容。结果是除了 AVAudioPlayer 及其依赖项（例如 NSObject 和 NSString）之外，什么都不包含。因此，您最终得到的是数万行绑定，而不是数百万行。

如果您需要更精细的控制，可以单独排除或包含所有声明，而不是使用 exclude-all-by-default

  functions:
    exclude:
      - '.*'
  structs:
    exclude:
      - '.*'
  unions:
    exclude:
      - '.*'
  globals:
    exclude:
      - '.*'
  macros:
    exclude:
      - '.*'
  enums:
    exclude:
      - '.*'
  unnamed-enums:
    exclude:
      - '.*'

所有这些 exclude 条目都排除了正则表达式 '.*'，它匹配任何内容。

您还可以使用 preamble 选项在生成的文件顶部插入文本。在此示例中，preamble 用于在生成的文件顶部插入一些 linter 忽略规则。

  preamble: |
    // ignore_for_file: camel_case_types, non_constant_identifier_names, unused_element, unused_field, return_of_invalid_type, void_checks, annotate_overrides, no_leading_underscores_for_local_identifiers, library_private_types_in_public_api

有关完整的配置选项列表，请参阅ffigen readme。

要生成绑定，请导航到示例目录，然后运行 ffigen

dart run ffigen

这将在 pubspec.yaml 文件中查找顶层的 ffigen 条目。如果您选择将 ffigen 配置放在单独的文件中，请使用 --config 选项并指定该文件。

dart run ffigen --config my_ffigen_config.yaml

对于此示例，这将生成 avf_audio_bindings.dart。

此文件包含一个名为 AVFAudio 的类，它是原生库包装器，使用 FFI 加载所有 API 函数，并提供方便的包装器方法来调用它们。此文件中的其他类都是我们需要的 Objective-C 接口（例如 AVAudioPlayer 及其依赖项）的 Dart 包装器。

现在您已准备好加载并与生成的库进行交互。示例应用 play_audio.dart 加载并播放作为命令行参数传入的音频文件。第一步是加载 dylib 并实例化原生 AVFAudio 库

import 'dart:ffi';
import 'avf_audio_bindings.dart';

const _dylibPath =
    '/System/Library/Frameworks/AVFAudio.framework/Versions/Current/AVFAudio';

void main(List<String> args) async {
  final lib = AVFAudio(DynamicLibrary.open(_dylibPath));

由于您正在加载一个内部库，因此 dylib 路径指向一个内部框架 dylib。您也可以加载自己的 .dylib 文件，或者如果库是静态链接到您的应用程序中（iOS 上通常如此），您可以使用 DynamicLibrary.process()。

  final lib = AVFAudio(DynamicLibrary.process());

本例的目标是逐个播放作为命令行参数指定的每个音频文件。对于每个参数，您首先必须将 Dart String 转换为 Objective-C NSString。生成的 NSString 包装器有一个方便的构造函数，可以处理此转换，以及一个 toString() 方法，可以将其转换回 Dart String。

  for (final file in args) {
    final fileStr = NSString(lib, file);
    print('Loading $fileStr');

音频播放器需要一个 NSURL，所以接下来我们使用 fileURLWithPath: 方法将 NSString 转换为 NSURL。由于 : 在 Dart 方法名中不是有效字符，它在绑定中被转换为 _。

    final fileUrl = NSURL.fileURLWithPath_(lib, fileStr);

现在，您可以构造 AVAudioPlayer。构造 Objective-C 对象有两个阶段。alloc 为对象分配内存，但不会初始化它。名称以 init* 开头的方法执行初始化。一些接口还提供 new* 方法，可以同时执行这两个步骤。

要初始化 AVAudioPlayer，请使用 initWithContentsOfURL:error: 方法

    final player =
        AVAudioPlayer.alloc(lib).initWithContentsOfURL_error_(fileUrl, nullptr);

Objective-C 使用引用计数进行内存管理（通过 retain、release 和其他函数），但在 Dart 端内存管理是自动处理的。Dart 包装器对象保留对 Objective-C 对象的引用，当 Dart 对象被垃圾回收时，生成的代码会自动使用 NativeFinalizer 释放该引用。

接下来，查找音频文件的长度，您稍后将需要它来等待音频播放结束。duration 是一个 @property(readonly)。Objective-C 属性在生成的 Dart 包装器对象上被转换为 getter 和 setter。由于 duration 是 readonly，因此只生成 getter。

结果 NSTimeInterval 只是一个类型别名 double，所以您可以立即使用 Dart 的 .ceil() 方法向上取整到下一秒。

    final durationSeconds = player.duration.ceil();
    print('$durationSeconds sec');

最后，您可以使用 play 方法播放音频，然后检查状态，并等待音频文件播放完成。

    final status = player.play();
    if (status) {
      print('Playing...');
      await Future<void>.delayed(Duration(seconds: durationSeconds));
    } else {
      print('Failed to play audio.');
    }

多线程问题是 Dart 对 Objective-C 互操作的实验性支持的最大限制。这些限制是由于 Dart 隔离区（isolates）与操作系统线程之间的关系，以及 Apple API 处理多线程的方式造成的。

• Dart 隔离区与线程不同。隔离区在线程上运行，但不保证在任何特定线程上运行，并且虚拟机可能会在没有警告的情况下更改隔离区运行的线程。有一个开放的功能请求，以实现隔离区可以固定到特定线程。
• 虽然 ffigen 支持将 Dart 函数转换为 Objective-C 块，但大多数 Apple API 不对回调将在哪个线程上运行做出任何保证。
• 大多数涉及 UI 交互的 API 只能在主线程上调用，在 Flutter 中也称为*平台*线程。
• 许多 Apple API 不是线程安全的。

前两点意味着在一个隔离区中创建的回调可能在运行另一个隔离区或根本没有隔离区的线程上被调用。根据您使用的回调类型，这可能导致您的应用程序崩溃。使用 Pointer.fromFunction 或 NativeCallable.isolateLocal 创建的回调必须在所有者隔离区的线程上调用，否则它们将崩溃。使用 NativeCallable.listener 创建的回调可以安全地从任何线程调用。

第三点意味着直接使用生成的 Dart 绑定调用某些 Apple API 可能不是线程安全的。这可能会导致您的应用程序崩溃，或导致其他不可预测的行为。您可以通过编写一些 Objective-C 代码将您的调用分派到主线程来解决此限制。有关更多信息，请参阅 Objective-C dispatch 文档。

关于最后一点，尽管 Dart 隔离区可以切换线程，但它们一次只在一个线程上运行。因此，您正在交互的 API 不一定必须是线程安全的，只要它不是线程有害的，并且没有关于从哪个线程调用的限制。

只要您牢记这些限制，就可以安全地与 Objective-C 代码交互。

此示例演示了如何使 Swift 类与 Objective-C 兼容，生成包装器头文件，并从 Dart 代码中调用它。

通过使用 @objc 注解，Swift API 可以与 Objective-C 兼容。请确保您希望使用的任何类或方法都声明为 public，并且您的类继承自 NSObject。

import Foundation

@objc public class SwiftClass: NSObject {
  @objc public func sayHello() -> String {
    return "Hello from Swift!";
  }

  @objc public var someField = 123;
}

如果您试图与第三方库交互，并且无法修改其代码，您可能需要编写一个与 Objective-C 兼容的包装器类，以公开您想要使用的方法。

有关 Objective-C / Swift 互操作性的更多信息，请参阅 Swift 文档。

一旦您的类兼容，您就可以生成一个 Objective-C 包装器头文件。您可以使用 Xcode 或 Swift 命令行编译器 swiftc 来完成此操作。此示例使用命令行：

swiftc -c swift_api.swift             \
    -module-name swift_module           \
    -emit-objc-header-path swift_api.h  \
    -emit-library -o libswiftapi.dylib

此命令编译 Swift 文件 swift_api.swift，并生成一个包装器头文件 swift_api.h。它还会生成您稍后将加载的 dylib libswiftapi.dylib。

您可以通过打开生成头文件并检查接口是否符合预期来验证它是否正确生成。在文件底部，您应该会看到类似以下内容：

SWIFT_CLASS("_TtC12swift_module10SwiftClass")
@interface SwiftClass : NSObject
- (NSString * _Nonnull)sayHello SWIFT_WARN_UNUSED_RESULT;
@property (nonatomic) NSInteger someField;
- (nonnull instancetype)init OBJC_DESIGNATED_INITIALIZER;
@end

如果接口缺失，或者不包含所有方法，请确保它们都用 @objc 和 public 注解。

Ffigen 只看到 Objective-C 包装器头文件 swift_api.h。因此，此配置的大部分内容与 Objective-C 示例相似，包括将语言设置为 objc。

ffigen:
  name: SwiftLibrary
  description: Bindings for swift_api.
  language: objc
  output: 'swift_api_bindings.dart'
  exclude-all-by-default: true
  objc-interfaces:
    include:
      - 'SwiftClass'
    module:
      'SwiftClass': 'swift_module'
  headers:
    entry-points:
      - 'swift_api.h'
  preamble: |
    // ignore_for_file: camel_case_types, non_constant_identifier_names, unused_element, unused_field, return_of_invalid_type, void_checks, annotate_overrides, no_leading_underscores_for_local_identifiers, library_private_types_in_public_api

像以前一样，将语言设置为 objc，入口点设置为头文件；默认情况下排除所有内容，并明确包含您正在绑定的接口。

包装的 Swift API 配置与纯 Objective-C API 配置之间有一个重要区别：objc-interfaces -> module 选项。当 swiftc 编译库时，它会给 Objective-C 接口添加一个模块前缀。在内部，SwiftClass 实际上注册为 swift_module.SwiftClass。您需要将此前缀告知 ffigen，以便它从 dylib 中加载正确的类。

并非每个类都会获得此前缀。例如，NSString 和 NSObject 不会获得模块前缀，因为它们是内部类。这就是为什么 module 选项将类名映射到模块前缀的原因。您还可以使用正则表达式一次匹配多个类名。

模块前缀是您传递给 swiftc 的 -module-name 标志的值。在此示例中，它是 swift_module。如果您没有明确设置此标志，它将默认为 Swift 文件的名称。

如果您不确定模块名称是什么，也可以检查生成的 Objective-C 头文件。在 @interface 的上方，您会找到一个 SWIFT_CLASS 宏。

SWIFT_CLASS("_TtC12swift_module10SwiftClass")
@interface SwiftClass : NSObject

宏内的字符串有点神秘，但您可以看到它包含模块名和类名："_TtC12swift_module10SwiftClass"。

Swift 甚至可以为我们解构这个名称。

echo "_TtC12swift_module10SwiftClass" | swift demangle

这会输出 swift_module.SwiftClass。

像以前一样，导航到示例目录，然后运行 ffigen

dart run ffigen

这将生成 swift_api_bindings.dart。

与这些绑定的交互方式与普通的 Objective-C 库完全相同。

import 'dart:ffi';
import 'swift_api_bindings.dart';

void main() {
  final lib = SwiftLibrary(DynamicLibrary.open('libswiftapi.dylib'));
  final object = SwiftClass.new1(lib);
  print(object.sayHello());
  print('field = ${object.someField}');
  object.someField = 456;
  print('field = ${object.someField}');
}

请注意，模块名称在生成的 Dart API 中没有提及。它仅在内部使用，用于从 dylib 加载类。

现在您可以使用以下命令运行示例：

dart run example.dart