插件开发指南

更新: 2025/7/20 字数: 0 字 时长: 0 分钟

开发环境准备

要开发 Android 插件，推荐使用 Android Studio 作为主要开发工具。请确保你已完成以下准备工作：

• 安装最新版本的 Android Studio
• 正确配置 SDK 和 Gradle 构建环境
• 具备基础操作能力，例如：
  • 创建 Android 项目
  • 添加依赖和模块
  • 编译与打包 APK

如果你是第一次使用 Android Studio，建议先阅读 官方入门文档。

如何开发一个插件

本示例中的包名均为com.cloud.plugin.sdk.demo，在实际项目中插件包名可能有所不同。

插件SDK集成

新建一个Android项目，在项目的build.gradle文件中添加：

allprojects {
    repositories {
        // ...
        maven { url 'https://jitpack.io' }
    }
}

在具体模块(比如app)的build.gradle文件中添加：

dependencies {
    // ... 
    implementation 'com.github.CloudControlPro:sdk:1.0.0'
}

更多信息参见Jitpack.io 。

插件配置

1. 新建PluginHelloWorld文件，继承于Plugin.

public class PluginHelloWorld extends Plugin {

    public PluginHelloWorld(Context context, Context selfContext, Object runtime, Object topLevelScope) {
        super(context, selfContext, runtime, topLevelScope);
    }

    // 返回插件的JavaScript胶水层代码的assets目录路径
    @Override
    public String getAssetsScriptDir() {
        return "js-plugin";
    }

    // 插件public API，可被JavaScript代码调用
    public String getStringFromJava() {
        return "Hello, Bot.js!";
    }

    // 插件public API，可被JavaScript代码调用
    public void say(String message) {
        getSelfContext().startActivity(new Intent(getSelfContext(),  HelloWorldActivity.class)
                .putExtra("message", message)
                .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
    }
}

2. 新增MyPluginRegistry文件，继承于PluginRegistry:

public class MyPluginRegistry extends PluginRegistry {

    static {
        // 注册默认插件
        registerDefaultPlugin(new PluginLoader() {
            @Override
            public Plugin load(Context context, Context selfContext, Object runtime, Object topLevelScope) {
                return new PluginHelloWorld(context, selfContext, runtime, topLevelScope);
            }
        });
    }
}

在AndroidManifest.xml中配置以下meta-data, name为"org.cloud.plugin.sdk.registry"，value为MyPluginRegistry的包名。

  <application
        ...>

        <meta-data
            android:name="org.cloud.plugin.sdk.registry"
            android:value="com.cloud.plugins.sdk.demo.MyPluginRegistry" />

        <activity
            android:name=".HelloWorldActivity"
            android:exported="true" />

        <service
            android:name=".HelloworldPluginService"
            android:exported="true" />
    </application>

3. 编写JavaScript胶水层

在assets的相应目录(由Plugin.getAssetsScriptDir返回)中添加index.js文件，用于作为胶水层导出插件API。

module.exports = function (plugin) {
    let runtime = plugin.runtime;
    let scope = plugin.topLevelScope;

    function helloWorld() {
    }

    helloWorld.stringFromJava = plugin.getStringFromJava();

    helloWorld.say = function (message) {
        plugin.say(message);
    }

    return helloWorld;
}

4. 在Bot.js Pro中调用

编译插件为apk(assembleDebug/assembleRelease)，安装到设备上。在Bot.js Pro中使用以下代码调用：

let helloWorld = $plugins.load("com.cloud.plugins.sdk.demo");
console.log(helloWorld.stringFromJava);
helloWorld.say("Hello, Bot.js Pro Plugin");

5. 独立服务AIDL方式调用

可以在插件中编写一个Service，由Bot.js Pro唤起和绑定，并可在js中通过aidl调用Service的接口。

在Plugin中重写方法getService。

// 插件服务类，可选，用于AIDL方式和Bot.js Pro本体通信。可返回null
@Override
public ComponentName getService() {
    return new ComponentName(getSelfContext().getPackageName(), HelloworldPluginService.class.getName());
}

新建一个Service组件（注意在AndroidManifest中注册时需要是exported="true")，继承于PluginService。

public class HelloworldPluginService extends PluginService {
    private static final String ACTION_ADD = "add";

    @Override
    protected Result onRemoteCall(@NonNull String action, @NonNull Map<String, Object> args, @Nullable RemoteCallback callback) throws RuntimeException {
        switch (action) {
            case ACTION_ADD:
                return invokeAdd(args);
        }
        return Result.notImplemented(action);
    }

    private Result invokeAdd(Map<String, Object> args) {
        Number a   = PluginUtils.getNotNull(args, "a");
        Number b   = PluginUtils.getNotNull(args, "b");
        double sum = a.doubleValue() + b.doubleValue();
        return new Result(Collections.singletonMap("sum", sum));
    }
}

在index.js中添加胶水层代码:

helloWorld.remoteAdd = function (a, b) {
    return plugin.waitForConnection().call('add', {
        a: a,
        b: b
    }, null).get('sum');
}

然后可以在Bot.js Pro中调用：

let helloWorld = $plugins.load("com.cloud.plugins.sdk.demo");
console.log(helloWorld.remoteAdd(1, 2));