使用 dart:ffi 進行 C 語言互操作

執行在 Dart 原生平臺上的 Dart 移動、命令列和伺服器應用可以使用 dart:ffi 庫呼叫原生 C API，以及讀、寫、分配和釋放原生記憶體。FFI 是 Foreign Function Interface 的縮寫，意為外部函式介面。類似功能的其他術語包括原生介面和語言繫結。

API 文件可在dart:ffi API 參考中查閱。

要使用本指南中的示例，請下載完整的 ffi 示例目錄。它包括以下示例，展示如何使用 dart:ffi 庫

要了解如何使用 dart:ffi 庫呼叫 C 函式，請回顧 hello.dart 檔案。本節解釋了該檔案的內容。

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. 為呼叫 C 函式時要使用的變數建立 typedef。

   dart

   typedef HelloWorld = void Function();

5. 建立一個變數來儲存動態庫的路徑。

   dart

   final String libraryPath;
   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',
     );
   } else {
     libraryPath = path.join(
       Directory.current.path,
       'hello_library',
       'libhello.so',
     );
   }

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 構建鉤子（以前稱為原生資產）使包除了 Dart 原始碼外，還能包含更多內容。現在，包可以包含原生程式碼資產，這些資產會被透明地構建、打包並在執行時可用。

此功能簡化了 Dart 包依賴和使用原生程式碼的方式

• 使用包的構建鉤子（位於 hook/build.dart 中）構建原生程式碼或獲取二進位制檔案。
• Dart 和 Flutter 會打包構建鉤子報告的 CodeAsset。
• 透過使用 assetId 的宣告式 @Native<>() extern 函式在執行時訪問程式碼資產。

Flutter 和獨立的 Dart 會自動打包應用使用的所有包的原生程式碼，並在執行時使其可用。這適用於 flutter (run|build) 和 dart (run|build) 命令。

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:hooks API 參考。

要提供反饋，請參考這些跟蹤議題

• Dart 構建鉤子與程式碼資產
• Flutter 構建鉤子與程式碼資產