Cocotais Bot

主题

插件开发(旧) Deprecated ​

危险

当前页面下的内容已过时。请参考 更新指导 了解如何升级。

本页面将会带你走进 Cocotais Bot 的插件开发。

要想在最佳条件下开发你的插件，请务必提前在你的项目文件夹下 部署一个机器人实例。

STEP 1：新建插件文件 ​

一般来说，Cocotais Bot 的插件都存放在项目目录中的 plugins 文件夹中，你可以提前手动创建这个文件夹。

信息

自 v1.2.2 开始，插件编写允许使用 ESM 模块的写法。如果你需要使用 ESM 模块写法，请将创建的插件文件后缀名改为 .mjs。

接下来，在文件夹下新建一个文件 my_first_plugin.js ( ESM: my_first_plugin.mjs )。 现在你的目录树看起来应该是这样的：

.
├─ plugins
│  └─ my_first_plugin.js
├─ config.json
├─ package.json
└─ package-lock.json
.
├─ plugins
│  └─ my_first_plugin.mjs
├─ config.json
├─ package.json
└─ package-lock.json

STEP 2：新建插件实例 ​

Cocotais Bot 为了方便插件的开发，向外部导出了一个 CocotaisBotPlugin 类。它可以帮助我们实现一个插件。

要想使用它，可以这样引入：

js
const { CocotaisBotPlugin } = require("cocotais-bot");
js
import { CocotaisBotPlugin } from "cocotais-bot";

接下来，是时候用它创建一个插件了！

警告

当你的版本 ≤ v1.1.2 时，你将无法在 CocotaisBotPlugin 的构造器中传值。你的插件名称将会被强制设置为 plugin，版本不会被定义。

js
const plugin = new CocotaisBotPlugin("my-first-plugin", "0.1.0");

其中，CocotaisBotPlugin 构造器接受了两个参数：

名称类型解释必填
namestring插件名称√
versionstring插件版本√

STEP 3：编写业务逻辑 ​

为了让你的插件能够知道自己被安装或者卸载了，CocotaisBotPlugin 类实现了两个方法：onMounted 和 onUnloaded 。要想让插件正确收到事件，请务必将业务逻辑写在 onMounted 中。同时，如果你不使用 onMounted，你将无法正常获得机器人的控制对象 IOpenAPI。

CocotaisBotPlugin 类是继承了 EventEmitter 的。你可以使用 EventEmitter 几乎所有的方法，on 也不例外：

js
plugin.onMounted((bot)=>{
    plugin.on("GROUP_AT_MESSAGE_CREATE",(event)=>{
        // ...
    })
})

信息

在 v1.3.1 以前，on 方法的事件并不支持语法补全。我们推荐在编写插件时安装最新的 Cocotais Bot 版本。

信息

在以前，on 方法的接收函数并不支持语法补全。它目前的定义类似于这样：

ts
on(event: AllEvents, listener: Function): this;

在版本号≥v1.4.0-0的版本中，已经得到了增强：

ts
on<T extends keyof EventList>(event: T, listener: (arg: EventList[T]) => void): this;

plugin.onMounted 函数里，接收函数的参数 bot 的类型是 IOpenAPI，这是机器人的控制对象，内包含机器人的各种收发方法。

提示

在版本号＜v1.4.0-0的版本中，plugin.on 函数里接收函数的参数 event 的类型为 any，为了避免出现问题，你可以对照 QQ 机器人文档 里的 事件 文档 和 接收到的通知示例 进行编写。我们还是推荐使用最新版本进行插件的开发。

这是一个简单的示例：

js
plugin.onMounted((bot) => {
    plugin.on("GROUP_AT_MESSAGE_CREATE", (event) => {
        bot.groupApi.postMessage(event.msg.group_openid, {
            content: "Hi",
            msg_type: 0,
            msg_id: event.msg.id
        });
    });
});

实现了当收到群@消息时，会自动对消息回复 Hi。

STEP 4：导出插件实例 ​

在编写完插件的主要逻辑后，是时候导出插件了。Cocotais Bot 仅支持将插件设置为默认导出：

js
module.export = plugin;
js
export default plugin;

这是完整的插件示例：

js
const { CocotaisBotPlugin } = require("cocotais-bot");

const plugin = new CocotaisBotPlugin("my-first-plugin", "0.1.0");

plugin.onMounted((bot) => {
    plugin.on("GROUP_AT_MESSAGE_CREATE", (event) => {
        bot.groupApi.postMessage(event.msg.group_openid, {
            content: "Hi",
            msg_type: 0,
            msg_id: event.msg.id
        });
    });
});

module.export = plugin;
js
import { CocotaisBotPlugin } from "cocotais-bot";

const plugin = new CocotaisBotPlugin("my-first-plugin", "0.1.0");

plugin.onMounted((bot) => {
    plugin.on("GROUP_AT_MESSAGE_CREATE", (event) => {
        bot.groupApi.postMessage(event.msg.group_openid, {
            content: "Hi",
            msg_type: 0,
            msg_id: event.msg.id
        });
    });
});

export default plugin;

STEP 5：运行插件 ​

在完成插件的编写后，是时候运行插件，验收你的学习成果了！返回你的项目根目录，运行以下命令：

bash
npx cocotais-bot start

信息

自 v1.2.0-0 开始，在运行 npx cocotais-bot start 时会自动装载 plugins 文件夹下的所有插件。 如果你的版本 ＜ v1.2.0-0，请再多运行一行：

bash
npx cocotais-bot plugin apply ./plugins/my_first_plugin.js

此时，你的机器人应该已经启动，并且插件也正常运行，可以尝试在群里@机器人进行测试。

测试完毕后，运行以下命令：

bash
npx cocotais-bot plugin list

你应该可以看到你的插件名称和版本。

恭喜你，完成了你的第一个插件的开发！

© Cocotais 2024