内容

使用 package:ffigen 进行 Objective-C 和 Swift 互操作

在 macOS 或 iOS 上的 Dart Native 平台 上运行的 Dart 移动端、命令行和服务器应用可以使用 dart:ffipackage: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:ffipackage:ffigen 能够与 Swift 交互。

Objective-C 示例

#

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

$ xcodebuild -showsdks

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

package:ffigen 使用 LLVM 解析 Objective-C 头文件,因此你需要先安装它。有关更多详细信息,请参阅 ffigen 自述文件中的 安装 LLVM

配置 ffigen

#

首先,将 package:ffigen 添加为开发依赖项

$ dart pub add --dev ffigen

然后,配置 ffigen 以为包含 API 的 Objective-C 头文件生成绑定。ffigen 配置选项位于 pubspec.yaml 文件中的顶级 ffigen 条目下。或者,你可以将 ffigen 配置放入其自己的 .yaml 文件中。

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 感兴趣,因此你可以排除所有其他内容

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

由于 AVAudioPlayer 是这样明确包含的,ffigen 排除了所有其他接口。exclude-all-by-default 标志告诉 ffigen 排除其他所有内容。结果是除了 AVAudioPlayer 及其依赖项(如 NSObjectNSString)之外,其他所有内容都被排除在外。因此,你最终得到的不是数百万行的绑定,而是数万行。

如果你需要更精细的控制,你可以逐个排除或包含所有声明,而不是使用 exclude-all-by-default

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

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

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

yaml
  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 自述文件

生成 Dart 绑定

#

要生成绑定,请导航到示例目录并运行 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 接口的 Dart 包装器,例如 AVAudioPlayer 及其依赖项。

使用绑定

#

现在,您可以加载并与生成的库进行交互。示例应用程序 play_audio.dart 加载并播放作为命令行参数传递的音频文件。第一步是加载 dylib 并实例化本机 AVFAudio

dart
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()

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

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

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

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

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

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

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

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

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

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

生成的 NSTimeInterval 只是一个类型别名为 double,因此你可以立即使用 Dart .ceil() 方法向上舍入到下一秒

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

最后,你可以使用 play 方法来播放音频,然后检查状态,并等待音频文件持续时间

dart
    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 隔离和操作系统线程之间的关系,以及 Apple 的 API 处理多线程的方式

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

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

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

关于最后一点,尽管 Dart 隔离可以切换线程,但它们一次只在一个线程上运行。因此,只要它不是线程敌对的并且没有关于从哪个线程调用它的约束,那么你正在交互的 API 就不必一定是线程安全的。

只要记住这些限制,就可以安全地与 Objective-C 代码进行交互。

Swift 示例

#

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

生成 Objective-C 包装器头文件

#

可以通过使用 @objc 注解使 Swift API 与 Objective-C 兼容。确保将要使用的任何类或方法设为 public,并使你的类扩展 NSObject

swift
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

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

objc
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

如果缺少接口或不包含所有方法,请确保它们都用 @objcpublic 进行注释。

配置 ffigen

#

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

yaml
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 加载正确的类。

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

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

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

objc
SWIFT_CLASS("_TtC12swift_module10SwiftClass")
@interface SwiftClass : NSObject

宏中的字符串有点神秘,但您可以看到它包含模块名称和类名:"_TtC12swift_module10SwiftClass"

Swift 甚至可以为我们解析此名称

$ echo "_TtC12swift_module10SwiftClass" | swift demangle

这会输出 swift_module.SwiftClass

生成 Dart 绑定

#

与之前一样,导航到示例目录,并运行 ffigen

$ dart run ffigen

这会生成 swift_api_bindings.dart

使用绑定

#

与这些绑定进行交互与普通 Objective-C 库完全相同

dart
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