1
前置條件
開始之前，請確保你已準備好：
- HarmonyOS（API 12+）設備或模擬器
- DevEco Studio 和 HarmonyOS SDK
- 一個
.so共享庫（預編譯或從源碼編譯）
| 架構 | ABI | 說明 |
|---|---|---|
| ARM64 | arm64-v8a | 預設支援，已驗證 |
| x86_64 | x86_64 | 需在 abiFilters 中新增 |
| RISC-V 64 | riscv64 | 需外部工具鏈；DevEco Studio 不直接支援 RISC-V 構建 |
2
添加 library 模塊
在項目中添加 HAR 模塊：
Project/
└── library/
├── src/main/cpp/ # 原生 C++ 代碼
├── src/main/ets/ # ArkTS/TS 封裝
├── build-profile.json5
└── oh-package.json5
3
配置原生構建
{
"buildOption": {
"externalNativeOptions": {
"path": "./src/main/cpp/CMakeLists.txt",
"abiFilters": ["arm64-v8a", "x86_64", "riscv64"]
}
}
}
cmake_minimum_required(VERSION 3.5.0)
add_library(library SHARED napi_init.cpp)
target_link_libraries(library PUBLIC libace_napi.z.so)
4
導入並使用
import { dlopen, FFIType, CString, CFunction, JSCallback } from 'arkffi';
const lib = dlopen('libmylib.so', {
calculate: {
args: [FFIType.int32, FFIType.double, FFIType.CString],
returns: FFIType.double,
},
});
lib.symbols.calculate(42, 3.14, 'hello');
lib.close();
5
使用原始橋接
需要更底層的控制時，可直接使用 NAPI 函數：
import ffi from 'liblibrary.so';
const handle = ffi.load('libffi_target.so');
ffi.defineFunction(handle, 'add', 'dd', 'd');
const sum = ffi.callBySig(handle, 'add', [2.0, 3.0], []);
ffi.close(handle);
6
操作 C 指針
const ptr = ffi.getSymbolPtr(handle, 'add');
ffi.callPtr(ptr, 'dd', 'd', [2.0, 3.0], []);
const cstr = new CString(ptr);
cstr.toString();
cstr.length;
7
創建回調
const cb = new JSCallback(
(a: number, b: number): number => a + b,
{ args: [FFIType.int32, FFIType.int32], returns: FFIType.int32 },
);
cb.call(2, 3); // → 5
cb.ptr; // → 槽位句柄
cb.close();