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

想要在应用中集成Android特性 Capacitor app? app? Capacitor 插件 __CAPGO_KEEP_0__ plugins

context: Page/area: Capgo solutions marketing page. Role: Short UI label or navigation item. Seen in: page solutions/webapp-to-mobile.astro. Preserve Capgo product/brand and developer terms exactly. Message key `solutions_webapp_to_mobile_link_plugins` (Solutions Webapp To Mobile Link Plugins).

• to combine native Android functionality with cross-platform web apps. 预打包的Android库，包含code、资源和原生文件。
• What are AAR files? 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 插件中，解锁本地 Android 能力以便于您的 Web 应用。

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

开发环境要求

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

所需软件

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

另外，请确保以下组件包含在您的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 with these settings to include AAR file support: .gitignore Configure Android Studio Settings .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'
}

• 将配置文件放在供应商特定的子目录中有助于保持组织结构并避免在处理多个AAR依赖项时出现的构建冲突。

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

Gradle

配置步骤 Gradle构建工具接口

要将AAR文件集成到您的__CAPGO_KEEP_0__插件中，您需要配置Gradle。首先，请在文件中添加以下仓库设置：

为了在Capacitor插件中集成AAR文件，您需要适当配置Gradle。首先在您的Capacitor插件中添加以下仓库设置。 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
    }
}

对于大型AAR文件，您可能需要增加Gradle的内存分配 gradle.properties:

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

完成同步后，您的 AAR 文件应已完全集成并准备就绪，待测试。

将 AAR 功能连接到 Capacitor

编写插件类

完成 Gradle 文件同步后，需要通过继承来连接 AAR 功能的 插件 类。这一步连接了 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 库所需的内容如下：

创建插件方法

接下来，使用注解定义您的插件方法。这些方法处理 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);
    }
}

对于需要异步运行的任务:

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

文件中的版本冲突。您可以强制使用特定版本来解决冲突：

确保 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 的性能选项卡监控运行时稳定性。对于初始化问题，处理异常时要小心:

为了防止内存泄漏，确保资源被正确释放。使用 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文件

如果您正在使用 How to Use AAR Files in Capacitor Plugins 来规划原生插件工作，连接它与 Capgo 插件目录 为产品工作流程在Capgo插件目录中 Capacitor 插件由 Capgo Capacitor 插件中的实现细节在 Capacitor 中，具体信息由 Capgo 提供。 添加或更新插件 为添加或更新插件的实现细节 Ionic 企业插件替代品 为 Ionic 企业插件替代品的产品工作流程 Capgo 原生构建 为产品工作流程在 Capgo 原生构建中。