使用 dart:ffi 进行 C 互操作

在 Dart 原生平台 (/overview#platform) 上运行的 Dart 移动应用、命令行应用和服务器应用可以使用 dart:ffi 库调用本机 C API，以及读取、写入、分配和释放本机内存。FFI 代表 外部函数接口 。类似功能的其他术语包括 原生接口 和 语言绑定 。

API 文档可在 dart:ffi API 参考 中找到。

要使用本指南中的示例，请下载完整的 ffi 示例 目录。它包含以下示例，演示如何使用 dart:ffi 库：

hello_world 示例 包含调用 C 库所需的最小代码。此示例可在您在上一步下载的 samples/ffi 中找到。

hello_world 示例包含以下文件：

构建 C 库会创建多个文件，包括名为 libhello.dylib （macOS）、 libhello.dll （Windows）或 libhello.so （Linux）的动态库文件。

构建动态库和执行 Dart 应用的命令类似于以下系列。

$ cd hello_library
$ cmake .
...
$ make
...
$ cd ..
$ dart pub get
$ dart run hello.dart
Hello World

要了解如何使用 dart:ffi 库调用 C 函数，请查看 hello.dart 文件 。本节解释此文件的内容。

1. 导入 dart:ffi 。

   dart

   import 'dart:ffi' as ffi;

2. 导入将用于存储动态库路径的 path 库。

   dart

   import 'dart:io' show Platform, Directory;
   import 'package:path/path.dart' as path;

3. 使用 C 函数的 FFI 类型签名创建 typedef。要了解根据 dart:ffi 库最常用的类型，请参阅 与原生类型接口 。

   dart

   typedef hello_world_func = ffi.Void Function();

4. 创建一个 typedef ，用于在调用 C 函数时使用的变量。

   dart

   typedef HelloWorld = void Function();

5. 创建一个变量来存储动态库的路径。

   dart

   var libraryPath = path.join(Directory.current.path, 'hello_library',
       'libhello.so');
   if (Platform.isMacOS) {
     libraryPath = path.join(Directory.current.path, 'hello_library',
         'libhello.dylib');
   } else if (Platform.isWindows) {
     libraryPath = path.join(Directory.current.path, 'hello_library',
         'Debug', 'hello.dll');
   }

6. 打开包含 C 函数的动态库。

   dart

   final dylib = ffi.DynamicLibrary.open(libraryPath);

7. 获取对 C 函数的引用，并将其放入变量中。此代码使用步骤 2 和 3 中的 typedefs ，以及步骤 4 中的动态库变量。

   dart

   final HelloWorld hello = dylib
       .lookup<ffi.NativeFunction<hello_world_func>>('hello_world')
       .asFunction();

8. 调用 C 函数。

   dart

   hello();

了解 hello_world 示例后，请参考 其他 dart:ffi 示例 。

捆绑/打包/分发然后加载本机 C 库的方法取决于平台和库类型。

要了解如何操作，请参考以下页面和示例。

• Flutter dart:ffi 用于 Android 应用
• Flutter dart:ffi 用于 iOS 应用
• Flutter dart:ffi 用于 macOS 应用
• dart:ffi 示例

dart:ffi 库提供了多个实现 NativeType 并表示 C 中原生类型的类型。您可以实例化一些原生类型。其他一些原生类型只能在类型签名中用作标记。

以下原生类型可以用作类型签名中的标记。它们或其子类型 可以 在 Dart 代码中实例化。

以下列表显示哪些平台无关的原生类型用作类型签名中的标记。它们 不能 在 Dart 代码中实例化。

还有许多 ABI 特定的标记原生类型扩展了 AbiSpecificInteger 。要了解这些类型如何在特定平台上映射，请参考以下表格中链接的 API 文档。

对于大型 API 表面，编写与 C 代码集成的 Dart 绑定可能非常耗时。要让 Dart 从 C 头文件中创建 FFI 包装器，

使用 package:ffigen 绑定生成器。

原生资源 功能应解决与分发依赖于原生代码的 Dart 包相关的一些问题。它通过提供统一的挂钩来集成构建 Flutter 和独立 Dart 应用程序时涉及的各种构建系统来实现此目的。

此功能应简化 Dart 包依赖和使用原生代码的方式。原生资源应提供以下好处：

• 使用包的 hook/build.dart 构建钩子构建原生代码或获取二进制文件。
• 捆绑 build.dart 构建钩子报告的原生 Asset 。
• 通过使用 assetId 的声明式 @Native<>() extern 函数在运行时使原生资源可用。

当您 选择加入 原生资源实验时， flutter (run|build) 和 dart (run|build) 命令将与 Dart 代码一起构建和捆绑原生代码。

native_add_library 示例包含在 Dart 包中构建和捆绑 C 代码的最小代码。

示例包含以下文件：

当 Dart 或 Flutter 项目依赖于 package:native_add_library 时，它会在 run 、 build 和 test 命令上调用 hook/build.dart 构建钩子。 native_add_app 示例展示了 native_add_library 的用法。

以下包的 API 文档：

• 要了解 Dart FFI 中的原生资源，请参阅 dart:ffi API 参考中的 Native 和 DefaultAsset 。
• 要了解 hook/build.dart 构建钩子，请参阅 package:native_assets_cli API 参考 。

要了解如何启用实验并提供反馈，请参阅以下跟踪问题：

• Dart 原生资源
• Flutter 原生资源

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。 查看源代码 或 报告问题.