如何在 Capacitor 插件中使用 AAR 文件

想将 Android 功能集成到您的 Capacitor 应用中吗？ 本指南将解释如何在 Capacitor 插件中 使用 AAR (Android Archive) 文件，将原生 Android 功能与跨平台 Web 应用结合起来。

核心要点：

• 什么是 AAR 文件？ 包含 code、资源和原生文件的预打包 Android 库。
• 为什么要使用它们？ AAR 文件可以实现 code 复用，简化维护并保护核心功能。
• 需要哪些工具？ 诸如 Android Studio, Gradle，以及 Node.js，以及正确的项目配置。
• 如何集成？ 将 AAR 文件放入 libs，配置 Gradle，并将其连接到 Capacitor 插件。

快速步骤：

1. 搭建开发环境： 安装所需工具并配置 Android Studio。
2. 整理项目结构： 为你的项目建立清晰的结构 Capacitor 插件.
3. 添加 AAR 文件： 将文件放入 android/libs 并更新 Gradle 依赖。
4. 编写 code 插件： 通过以下方式将 AAR 功能链接至 JavaScript： Capacitor 的 API.
5. 彻底测试： 使用 Android Studio 的 debugger 确保集成顺畅。

遵循本指南，您可以将 AAR 文件无缝集成到 Capacitor 插件中，为您的 Web 应用解锁原生 Android 能力。

How to embed an Android library (AAR file) into a capacitor 插件

开发环境配置要求

在开始处理 AAR 文件之前，请确保您的开发环境已正确配置，以避免出现任何问题。

所需软件

要在 Capacitor 插件中使用 AAR 文件，您需要以下软件：

此外，请确保您的 SDK Manager 中包含以下组件：

• Android SDK Platform 33 (Android 13.0)
• Android SDK Build-Tools 33.0.0
• Android SDK 命令行工具
• Android 模拟器
• Android SDK 平台工具

项目配置步骤

1. 初始化开发环境

首先，按照以下结构创建一个新目录：

my-plugin/
├── android/
│   ├── src/
│   └── build.gradle
├── src/
│   └── definitions.ts
└── package.json

2. 配置 Android Studio 设置

启动 Android Studio 并调整以下设置：

• 将 Gradle JDK 设置为 11 或更高版本。
• 启用 Android SDK 组件的自动下载功能。
• 更新系统环境变量，确保 Android SDK 路径正确。

3. 准备插件结构

更新 android/build.gradle 文件并应用以下设置，以支持 AAR 文件：

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. 配置版本控制

在项目目录中初始化 Git，并创建一个 .gitignore 文件来排除不必要的文件。这是一个示例 .gitignore:

android/build/
node_modules/
dist/
*.iml
.idea/
.gradle/
local.properties

完成这些步骤后，你就可以开始添加 AAR 文件了。

在插件中添加 AAR 文件

获取 AAR 文件

AAR 文件可能来自第三方 SDK、自定义库或 Maven 依赖。建议在 README 文件里记录它们的来源、版本和用途，该文件位于 libs 目录中。

准备好 AAR 文件并记录文档后，即可配置插件以包含它们。

配置插件文件

合理组织插件文件，以确保 AAR 依赖项能够顺利集成。以下是插件结构的示例：

my-plugin/
├── android/
│   ├── libs/        # AAR files with README
│   ├── src/
│   └── build.gradle
├── src/
│   └── definitions.ts
└── package.json
{
    "files": [
        "android/libs/*.aar",
        "android/src/**/*",
        "src/**/*"
    ]
}

AAR 文件存放位置

要启用 AAR 功能，请按照以下步骤将文件放入插件的 android/libs 目录中：

• 使用清晰且一致的命名格式，例如 libraryname-version.aar.
• 在以下文件中管理版本： versions.properties 例如：

library1=1.2.3
library2=2.0.0

• 添加一个 dependencies.gradle 用于其他依赖项的文件：

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    implementation 'com.example:dependency:1.0.0'
}

• 将特定厂商的文件组织到子目录中，以便更好地管理：

android/libs/
├── vendor1/
│   ├── feature.aar
│   └── config.json
└── vendor2/
    ├── module.aar
    └── settings.xml

将配置文件保留在特定厂商的子目录中，有助于保持条理性，并在处理多个 AAR 依赖项时避免构建冲突。

Gradle 配置步骤

更新 build.gradle

要在 Capacitor 插件中集成 AAR 文件，你需要正确配置 Gradle。首先，在以下文件中添加这些 repository 设置： android/build.gradle:

repositories {
    google()
    mavenCentral()
    flatDir {
        dirs 'libs'
    }
}

然后，在 dependencies 代码块中包含 AAR 依赖：

dependencies {
    implementation files('libs/your-library.aar')
    implementation fileTree(dir: 'libs', include: ['**/*.aar'])
    implementation "com.getcapacitor:core:${capacitorVersion}"
    implementation "androidx.appcompat:appcompat:1.6.1"
}

为了更好地进行版本管理，请在项目根目录创建一个 gradle.properties 文件并定义你的库版本：

# Library versions
MY_LIBRARY_VERSION=1.2.3
CAPACITOR_VERSION=5.5.0

如果 AAR 文件包含额外的依赖项，请按如下方式在 android/build.gradle 中进行声明：

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }

    packagingOptions {
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/LICENSE'
    }
}

完成这些更改后，请同步你的项目以应用配置。

正在运行 Gradle Sync

在 Android Studio 中打开项目，等待 Gradle 自动同步。如果未自动开始，请点击工具栏中的 “Sync Project with Gradle Files” 按钮。

同步完成后，请确认以下内容：

如果同步失败，请仔细检查配置。例如，确保已完成以下设置：

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    lintOptions {
        abortOnError false
    }
}

对于较大的 AAR 文件，你可能需要在以下文件中增加 Gradle 的内存分配： gradle.properties:

org.gradle.jvmargs=-Xmx2048m -XX:MaxPermSize=512m

同步成功完成后，你的 AAR 文件应已完全集成，可以开始测试。

将 AAR 功能连接至 Capacitor

编写 Plugin 类

Gradle 文件同步完成后，即可通过继承以下类来连接你的 AAR 功能： Plugin 类。此步骤将 JavaScript 与原生 Android code 进行关联。

@NativePlugin(
    permissions = {
        Manifest.permission.REQUIRED_PERMISSION
    }
)
public class YourPlugin extends Plugin {
    private YourAARLibrary libraryInstance;

    @Override
    public void load() {
        super.load();
        libraryInstance = new YourAARLibrary(getContext());
    }
}

初始化 AAR 库需要以下内容：

创建插件方法

接下来，使用 @PluginMethod 注解在插件中定义方法。这些方法负责 JavaScript 与 Java 之间的数据交换。

@PluginMethod
public void performAction(PluginCall call) {
    try {
        // Get data from JavaScript
        String inputData = call.getString("inputKey");

        // Call AAR library method
        YourLibraryResult result = libraryInstance.processData(inputData);

        // Return result to JavaScript
        JSObject ret = new JSObject();
        ret.put("value", result.getValue());
        call.resolve(ret);
    } catch (Exception e) {
        call.reject("Error processing data", e);
    }
}

对于需要异步执行的任务：

@PluginMethod(returnType = PluginMethod.RETURN_CALLBACK)
public void startContinuousOperation(PluginCall call) {
    call.setKeepAlive(true);

    libraryInstance.setCallback(new LibraryCallback() {
        @Override
        public void onUpdate(String data) {
            JSObject ret = new JSObject();
            ret.put("data", data);
            call.resolve(ret);
        }
    });
}

以下是常见类型在 JavaScript 与 Java 之间的转换方式：

如需清理资源，请重写 handleOnDestroy 方法：

@Override
protected void handleOnDestroy() {
    if (libraryInstance != null) {
        libraryInstance.cleanup();
        libraryInstance = null;
    }
    super.handleOnDestroy();
}

配置好这些方法后，你的原生桥接层就准备就绪了。请在 Android Studio 的调试环境中测试你的实现，以确保一切运行正常。

测试与问题修复

在 Android Studio 中调试

要在 Android Studio 中调试 AAR 集成情况，请先在项目的 build.gradle 文件：

android {
    buildTypes {
        debug {
            debuggable true
            minifyEnabled false
        }
    }
}

在插件方法中添加断点，以追踪数据流并定位潜在问题：

@PluginMethod
public void yourMethod(PluginCall call) {
    // Set a breakpoint here to inspect input data
    String inputValue = call.getString("key");
    // Another breakpoint here to check method calls to the AAR
    libraryInstance.someMethod(inputValue);
}

使用 Android Studio 中的 Debug 面板来监控关键区域：

如果调试无法解决问题，请参考下一节中的排查步骤。

排查步骤

如果仅靠调试还不够，请尝试以下步骤来解决常见问题：

1. 依赖冲突

检查你的 build.gradle 文件中的版本冲突。你可以强制指定特定版本来解决冲突：

configurations.all {
    resolutionStrategy {
        force 'com.google.android:android:4.1.1.4'
        // Add other forced versions as needed
    }
}

2. 缺失 Native 库

确保 AAR 包含了必要的 .so 并将其放在正确的目录中，例如：

• jniLibs/armeabi-v7a/
• jniLibs/arm64-v8a/
• jniLibs/x86/
• jniLibs/x86_64/

3. Manifest 合并问题

如果遇到 Manifest 冲突，请在你的 AndroidManifest.xml 文件中添加以下内容，以覆盖有问题的库：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="your.plugin.package">
    <uses-sdk tools:overrideLibrary="conflicting.library.package"/>
</manifest>

4. 运行时崩溃与内存管理

使用 Android Studio 中的 Performance 标签页来监控运行时稳定性。对于初始化问题，请务必谨慎处理异常：

try {
    libraryInstance = new YourAARLibrary(getContext());
} catch (Exception e) {
    Log.e("PluginError", "Failed to initialize library: " + e.getMessage());
    return;
}

为防止内存泄漏，请确保资源已正确释放。使用 Android Studio 中的 Memory Profiler 来追踪堆内存使用情况并识别泄漏。

总结

要在 Capacitor 插件中集成 AAR 文件，你需要配置 Android 环境、放置 AAR 文件、准确配置 Gradle 并进行充分测试。

核心实施阶段

掌握这些基础知识后，你可以进一步探索更高级的技术。

下一步

若要优化你的插件，请重点关注以下领域：

• 性能优化
  使用 Android Studio 的 profiler 监控内存使用情况，确保资源得到妥善释放。

• 发布准备
  记录所有 AAR 配置，生成 API 文档，并测试与 Android API 版本 29–34 的兼容性。

• 维护策略
  实现自动化测试，通过版本控制管理 AAR 版本，维护更新日志 (changelog)，并配置错误报告以解决生产环境问题。

如果你计划公开分享插件，请务必提供有关 AAR 特定设置及平台限制的详细文档。这将帮助其他开发者更轻松地接入并高效使用你的插件。

继续阅读：如何在 Capacitor 插件中使用 AAR 文件

如果你正在使用 如何在 Capacitor 插件中使用 AAR 文件 要规划原生插件工作，请将其连接到 Capgo 插件目录 用于 Capgo 插件目录中的产品工作流， 由 Capgo 提供的 Capacitor 插件 有关 Capgo 编写的 Capacitor 插件实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节， Ionic Enterprise 插件替代方案 了解 Ionic Enterprise 插件替代方案的产品工作流，以及 Capgo Native Build 关于 Capgo Native Builds 中的产品工作流。