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

想将Android功能整合到您的 Capacitor 应用程序中? 本指南解释了如何在 Capacitor 插件中使用AAR(Android Archive)文件

以结合原生Android功能和跨平台Web应用程序。

• 关键要点: Pre-packaged Android libraries containing code, resources, and native files.
• 预打包的Android库，包含__CAPGO_KEEP_0__、资源和原生文件。 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 的调试器来确保 smooth 的集成。

通过遵循本指南，您可以无缝地将 AAR 文件集成到您的 Capacitor 插件中，解锁 native Android 能力以便于您的 web 应用。

如何嵌入一个 Android 库（AAR 文件）到一个 capacitor 插件

开发环境配置要求

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

所需软件

以下是您需要与 AAR 文件一起工作的 Capacitor 插件的软件：

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

• Android SDK 平台 33 (Android 13.0)
• Android SDK 构建工具 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. 准备您的插件结构

更新文件以包含 AAR 文件支持的这些设置： android/build.gradle 设置版本控制

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. 在项目目录中初始化 Git 并创建一个

Initialize Git in your project directory and create a .gitignore file to exclude unnecessary files. Here’s a sample .gitignore:

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

完成这些步骤后，您将准备好添加您的 AAR 文件。

为插件添加 AAR 文件

获取 AAR 文件

AAR 文件可以来自第三方 SDK、自定义库或 Maven 依赖项。建议在文件中记录它们的来源、版本和目的，文件位于 README 目录下。 libs 来源类型

一旦您的 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

To integrate AAR files into your Capacitor plugin, you need to configure Gradle appropriately. Start by adding these repository settings to android/build.gradle:

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

然后，包括AAR依赖项在 dependencies 块：

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
    }
}

For large AAR files, you may need to increase Gradle’s memory allocation in __CAPGO_KEEP_0__. gradle.properties:

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

Once the sync completes successfully, your AAR files should be fully integrated and ready for testing.

将 AAR 功能与 Capacitor 相连

编写插件类

Once your Gradle files are synced, it’s time to connect your AAR functionality by extending the 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 file:

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. 缺少本机库

确保 AAR 包含所需的 .so 文件在适当的目录中，如:

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

3. 清单合并问题

如果您遇到清单冲突，请在文件中包含以下内容以覆盖问题库: AndroidManifest.xml 4. 运行时崩溃和内存管理

<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>

在 Android Studio 中使用性能 tab 监视运行时稳定性。对于初始化问题，处理异常时要小心：

为了防止内存泄露，确保资源被正确释放。使用 Android Studio 中的内存分析器来跟踪堆使用情况并识别任何泄露。

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

总结

要将 AAR 文件集成到 __CAPGO_KEEP_0__ 插件中，您需要设置 Android 环境、正确放置 AAR 文件、准确配置 Gradle 和进行彻底的测试。

To integrate AAR files into Capacitor plugins, you’ll need to set up the Android environment, place AAR files correctly, configure Gradle accurately, and test thoroughly.

__CAPGO_KEEP_0__

一旦你掌握了这些基本知识，你就可以探索更高级的技术了。

Next Steps

为了增强你的插件，重点关注以下方面：

• 性能优化
  使用 Android Studio 的 profiler 监控内存使用情况并确保资源被清理干净。

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

• 维护策略
  自动化测试，使用版本控制管理 AAR 版本，维护更改日志，并设置错误报告以解决生产问题。

如果您打算将插件公开分享，务必提供有关AAR特定设置和任何平台限制的详细文档。这将使其他开发人员更容易采用和使用您的插件。

从How to Use AAR Files in Capacitor Plugins继续

如果您正在使用 How to Use AAR Files in Capacitor Plugins 来规划原生插件工作，连接它与 Capgo Plugin Directory 为Capgo Plugin Directory中的产品工作流程 Capacitor Plugins by Capgo 为Capacitor Plugins by Capgo中的实现细节 添加或更新插件 为添加或更新插件中的实现细节 Ionic Enterprise Plugin Alternatives Ionic 企业插件替代品的产品工作流程，以及 Capgo 本机构建 for the product workflow in Capgo Native Builds.