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

想在您的 Capacitor app? 本指南将解释如何在 Capacitor 中使用 AAR (Android Archive) 文件

以结合原生 Android 功能和跨平台 web 应用。

• 关键点: Pre-packaged Android libraries containing code, resources, and native files.
• 预先打包的 Android 库，包含 __CAPGO_KEEP_0__、资源和原生文件。 AAR files enable code reuse, simplify maintenance, and protect proprietary features.
• AAR 文件使 __CAPGO_KEEP_0__ 重用变得简单，简化了维护，并保护了专有功能。 需要什么? 像 Android Studio 这样的工具, Gradle, 和 Node.js, 加上合适的项目设置。
• 如何集成? 将 AAR 文件放在 libs, 配置 Gradle, 并将它们连接到 Capacitor 插件。

快速步骤:

1. 设置环境: 安装所需工具并配置 Android Studio。
2. 组织项目: 为您的项目创建清晰的结构 Capacitor 插件.
3. 添加 AAR 文件： 将它们放置在 android/libs 并更新 Gradle 依赖项。
4. 编写插件 code： 将 AAR 功能与 JavaScript 链接起来，使用 __CAPGO_KEEP_0__ 的 __CAPGO_KEEP_1__ Capacitor’s API.
5. 使用 Android Studio 的调试器确保平滑的整合。 通过遵循本指南，您可以无缝地将 AAR 文件嵌入到您的 __CAPGO_KEEP_0__ 插件中，解锁本地 Android 能力以便于您的 web 应用。

如何将 Android 库（AAR 文件）嵌入到一个 Capacitor 中

AAR 文件 capacitor 插件

开发环境要求

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

所需软件

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

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

• 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 或更高版本。
• Enable the auto-download feature for Android SDK components.
• Update your system environment variables with the correct Android SDK path.

3. 准备插件结构

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

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }

    repositories {
        flatDir {
            dirs 'libs'
        }
    }
}

4. 在项目目录中初始化 Git 并创建文件以排除不必要的文件。以下是示例：

完成这些步骤后，您将准备好添加 AAR 文件。 .gitignore 将 AAR 文件添加到您的插件中 .gitignore:

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

获取 AAR 文件

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__

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 __CAPGO_KEEP_0__

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

然后，在 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

编写插件类

一旦Gradle文件同步完成，接下来就是连接AAR功能的时间，通过继承 插件 class. This step links JavaScript to the native 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());
    }
}

__CAPGO_KEEP_0__

创建插件方法

接下来，使用注解在您的插件中定义方法。这些方法处理JavaScript和Java之间的数据交换。 @PluginMethod 需要异步运行的任务:

@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);
    }
}

以下是JavaScript和Java之间常见类型的转换:

@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类型

为了资源清理，重写以下方法： 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.缺少本机库

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

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

3.清单合并问题

如果您遇到清单冲突，请在文件中包含以下内容以覆盖问题库: 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 tab 监视运行时稳定性。对于初始化问题，务必小心处理异常:

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

为了防止内存泄漏，确保资源正确释放。使用 Android Studio 中的 Memory Profiler 跟踪堆使用情况并识别任何泄漏。

总结

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

关键实施阶段

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

下一步

为了提高插件的性能，重点关注以下方面：

• 性能优化
  使用 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 原生构建中。