查看“新建模块指南”的源代码

本文将会教你如何编写自定义模块。

== 说明 ==
所有模块都储存在 <code>./modules/</code> 文件夹。如果你想编写新的模块，请在此新建一个文件夹。

文件夹的名字并不用于区分模块名，仅用于分类。

机器人在加载的时候会遍历 <code>./modules/</code> 文件夹，并加载每个模块文件夹里的 <code>__init__.py</code>，请将想要加入的模块定义编写在 <code>__init__.py</code> 中或确保其能够被引用。

== 编写 ==
我们假设你现在写好了具体的代码，现在你想把其做成一个可以给机器人使用的功能：

=== 定义模块 ===
在编写模块之前，我们需要先定义一个模块类型。

<syntaxhighlight lang="python3">
from core.component import module

test = module(
    bind_prefix='test1', # 定义模块名
    desc='这是一个简介', # 此模块的简介
    alias='t', # 此模块的别名
    developers=['Example'], # 开发者的名字
    recommend_modules=['test2', 'test3']), # 推荐启用的其他模块，用于在启用此模块时进行一并提示
    required_admin = False, # 将此模块标记为仅群组管理员可执行，覆盖下文所述的子命令设定，默认为False
    base = False, # 将此模块标记为基础模块，无需启用即可使用，默认为False
    required_superuser = False, # 将此模块标记为仅机器人超级管理员可使用，覆盖下文所述的子命令设定，默认为False
    support_languages=['zh_cn', 'zh_tw', 'en_us'] # 此模块支持的语言，未在列表内的语言在启用模块时会出现提醒
)
</syntaxhighlight>

=== 绑定模块 ===
现在你已经定义好了一个模块，现在你需要将你想要的东西绑定上去了。

在前文中，我们给 <code>test</code> 变量声明了定义，我们将围绕这个定义进行绑定子命令，为了使代码简洁，我们使用了装饰器：

==== Command（一般命令） ====
<syntaxhighlight lang="python3">
from core.builtins import Bot

@test.command(help_doc='<args1>', # 设置此命令的语法，前缀匹配模块名，此处忽略。可为 list 或 tuple 来经手多条命令。可为空。
             required_admin = False, # 将此命令标记为仅群组管理员可使用。
             required_superuser = False, # 将此命令标记为进机器人超级管理员可使用。
             available_for = '*' # 控制此命令可被使用的消息来源，默认为 '*'（所有）
             )
async def _(msg: Bot.MessageSession):
    ...
</syntaxhighlight>
当 <code>help_doc</code> 为空时，则代表此模块允许无需语法命令即可执行。如：使用 <code>~test</code> 命令（后面不带任何东西），即可触发装饰器下面的函数，否则会出现“语法错误”的提示。

与语法匹配的命令将会被切割存储于 <code>msg.parsed_msg</code>（dict 类型）

如：<code>{'<args1>': 'xxx'}</code>

==== Regex（正则表达式） ====
<syntaxhighlight lang="python3">
from core.builtins import Bot

@test.regex(pattern=r'\[\[(.*?)]]', # 正则表达式语法
            mode='M', # 正则模式，设为'M'为匹配模式，'A'为匹配所有模式
            flags=0, # 设置正则的flags，如Re.M|Re.I
            show_typing=False #设置命令执行时是否展示输入提示（如戳一戳），默认为True
             )
async def _(msg: Bot.MessageSession):
    ...
</syntaxhighlight>

与表达式匹配的命令结果将会存储于 <code>msg.matched_msg</code> 中。

当你输入的命令匹配 <code>help_doc</code> 内的语法时，机器人将会把消息传入装饰器下方的函数，然后你就可以进行发挥了。

==== Schedule（计划任务） ====
<syntaxhighlight lang="python3">
from core.builtins import Bot
from core.scheduler import CronTrigger

@test.schedule(trigger=CronTrigger.from_crontab('30 8 * * MON') # 触发此装饰器的条件)
async def _():
    ...
</syntaxhighlight>

==== FetchTarget ====
<syntaxhighlight lang="python3">
from core.builtins import Bot
...
await Bot.FetchTarget.post_message('test', '啊吧啊吧') # 向所有已开启 test 模块的用户推送消息。
sender = 'QQ|123456' # QQ号为123456的好友
fetch = Bot.FetchTarget.fetch_target(sender) # 获取信息
if fetch: #如获取到
    await fetch.sendMessage('xxx') # 发送消息
</syntaxhighlight>

主要用于从数据库中获取用户推送内容。

=== 通用装饰器 ===

假设你已经会使用了以上装饰器，而你又特别懒，则你可以使用通用装饰器来代替以上三种装饰器，此装饰器将会自动识别条件并归类函数。

<syntaxhighlight lang="python3">
from core.builtins import Bot

@test.handle('<args1>')
async def _(msg: Bot.MessageSession):
    ...


@test.handle(re.complie('(.*)'))
async def _(msg: Bot.MessageSession):
    ...


@test.handle(CronTrigger.from_crontab('30 8 * * MON'))
async def _():
    ...
</syntaxhighlight>

=== 处理消息 ===
我们在装饰器下方的函数定义了一个 msg 参数，发送消息将围绕它进行。
我们在此处仅展示基础方法，具体可用的操作请借助 IDE 查看。
<syntaxhighlight lang="python3">
...
send = await msg.sendMessage('你好。') # 向发送对象发送一条消息
send.delete() # 将这条消息删除
...
confirm = await msg.waitConfirm('你确定吗？') # 在发送此消息后将暂停执行，等待用户的下一条消息
if confirm: # 用户发送了确认的词语
    ...

</syntaxhighlight>
发送的消息可以为字符串或装有消息组件的列表，如：<code><nowiki>[Plain('今日图片：'), Image('https://example.com/test.jpg')]</nowiki></code>

=== 消息来源 ===
目前可用的消息来源（对话）有以下几种：
* QQ
** <code>QQ|Group</code>（QQ 群）
** <code>QQ</code>（QQ 好友）
** <code>QQ|Guild</code>（QQ 频道）
* Discord
** <code>Discord|Channel</code>（Discord 频道）
** <code>Discord|DM|Channel</code>（Discord 私聊频道）
* Telegram
** <code>Telegram|Private</code>（Telegram 私聊）
** <code>Telegram|Group</code>（Telegram 群组）
**<code>Telegram|Supergroup</code>（Telegram 超级群组）
** <code>Telegram|Channel</code>（Telegram 频道）
* Kook
** <code>Kook|Group</code>（Kook 频道）
* Matrix
** <code>Matrix|Room</code>（Matrix 聊天室）
* [[控制台]]
** <code>TEST|Console</code>

=== 消息组件 ===
目前主要可用的有<code>Plain</code>（文本）、<code>Image</code>（图片）、<code>Voice</code>（语音）

=== 别名 ===
主要用于快捷触发命令，或是兼容老的命令语法。
当为<code>str</code>、<code>List[str]</code>、<code>Tuple[str]</code>时，别名将会指向模块名。

如上文，<code>alias='t'</code>，则使用<code>~t xxx</code> = <code>~test1 xxx</code>

当为 dict 时则可自定义别名映射的命令，如<code>{'enable': 'module enable'}</code>，则<code>~enable xxx</code> = <code>~module enable xxx</code>

=== 多语言 ===
我们加入了多语言支持，所有的多语言文件在模块文件夹下的 <code>locales</code> 文件夹，其中 <code>zh_cn.json</code>、<code>en_us.json</code> 等 json 文件分别存储不同语言的键名。

目前官方存储库的大部分公开命令的多语言由机器人维护，新模块仅需在文件夹下存储<code>zh_cn.json</code>即可。

在代码中可通过<code>MessageSession.locale.t("键名")</code>调用多语言。命令帮助则是<code>{键名}</code>，如<code>test <arg1> <nowiki>{{help.test}}</nowiki></code> 

[[Category:开发]]
{{#dpl:category=开发|mode=userformat|format=,²{#related:%PAGE%}²,,|ordermethod=lastedit}}