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

想在应用中集成 Android 特性吗? Capacitor 应用 __CAPGO_KEEP_0__ Capacitor plugins 结合原生 Android 功能和跨平台 web 应用

关键点:

• 什么是 AAR 文件? 预打包的 Android 库，包含 code、资源和原生文件
• 为什么要使用它们? AAR 文件使 code 可复用、简化维护和保护专有功能
• 什么需要? 类似于 安卓Studio, Gradle，以及 Node.js，并且需要正确的项目设置
• 如何整合? 将 AAR 文件放在 libs，配置 Gradle，并将它们连接到 Capacitor 插件

快速步骤:

1. 设置您的环境: 安装所需工具并配置Android Studio。
2. 组织您的项目： 为您的 Capacitor.
3. 添加AAR文件： 将它们放置在 android/libs 并更新Gradle依赖项。
4. 写插件 code: __CAPGO_KEEP_0__： Capacitor的API.
5. __CAPGO_KEEP_0__的__CAPGO_KEEP_1__ 进行彻底测试：

通过遵循本指南，您可以轻松将 AAR 文件整合到您的 Capacitor 插件中，解锁 native Android 能力以便于您的 web 应用。

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

开发环境要求

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

所需软件

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

另外，请确保以下组件包含在您的SDK管理器中:

• AndroidSDK平台33（Android 13.0）
• AndroidSDK构建工具33.0.0
• AndroidSDK命令行工具
• Android模拟器
• AndroidSDK平台工具

项目设置步骤

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并创建一个文件来排除不必要的文件。以下是示例

file .gitignore file .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 要启用 AAR 功能，请将文件放在您的插件的

• 使用清晰一致的命名格式，例如 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

要将AAR文件集成到Capacitor插件中，您需要配置Gradle。首先，请在 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 {
    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

编写插件类

完成Gradle文件同步后，需要通过继承 插件 类来连接您的AAR功能。这一步将JavaScript与native Androidcode进行关联。

@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库所需的内容:

创建插件方法

接下来，使用注解定义您的插件方法。这些方法处理 JavaScript 和 Java 之间的数据交换。 @PluginMethod 在您的插件中使用 AAR 文件

@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的调试环境中，以确保一切正常工作。

测试和修复问题

在 安卓 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.缺少的本机库

确保 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;
}

总结

Summary

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.

阶段

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

下一步

为了增强您的插件，请关注以下方面：

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

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

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

如果您计划将插件公开分享，请确保提供详细的 AAR 特定设置文档和任何平台限制。这将使其他开发者更容易采用和使用您的插件。

继续阅读《在Capacitor插件中使用AAR文件》

如果您正在使用 《在Capacitor插件中使用AAR文件》 来规划原生插件工作，连接它与 Capgo插件目录 为Capgo插件目录中的产品工作流程 Capacitor插件由Capgo 为Capacitor插件由Capgo中的实现细节 添加或更新插件 为添加或更新插件中的实现细节 Ionic企业插件替代品 为Ionic企业插件替代品中的产品工作流程 Capgo 原生构建 为产品工作流程在 Capgo 原生构建中。