新建模块指南：修订间差异

可视化Wikitext

2023年3月4日 (六) 09:25的版本

~~不会吧不会吧，真的会有人来给屎山写模块吗（~~

说明

我们将所有模块储存在了modules文件夹。如果你想编写新的模块，请在里面新建一个文件夹。

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

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

编写

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

定义模块

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

from core.component import module

test = module(
    bind_prefix='test', # 定义模块名
    desc='啊吧啊吧啊吧', # 此模块的简介
    alias='m', # 此模块的别名，用法请见下文
    developers=['OasisAkari', 'Dianliang233'], # 开发者的名字
    recommend_modules=['mcbv', 'mcdv']), # 推荐打开的其他模块，用于在打开此模块时进行一并提示
    required_admin = False, # 将此模块标记为仅群组管理员可执行，覆盖下文所述的子命令设定，默认为False
    base = False, # 将此模块标记为基础模块，无需打开即可使用，默认为False
    required_superuser = False # 将此模块标记为仅机器人超级管理员可使用，覆盖下文所述的子命令设定，默认为False
)

绑定模块

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

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

Command（一般命令）

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):
    ...

当help_doc为空时，则代表此模块允许无需语法命令即可执行。如：使用~test命令（后面不带任何东西），即可触发装饰器下面的函数，否则会出现“语法错误”的提示。

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

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

Regex（正则表达式）

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):
    ...

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

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

Schedule（计划任务）

同理。

from core.builtins import Bot
from core.scheduler import CronTrigger

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

FetchTarget

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

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

通用装饰器

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

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 _():

...

处理消息

我们在装饰器下方的函数定义了一个msg参数，发送消息将围绕它进行。我们在此处仅展示基础方法，具体可用的操作请借助ide查看。

...
send = await msg.sendMessage('你好') # 向发送对象发送一条消息
send.delete() # 将这条消息删除
...
confirm = await msg.waitConfirm('真的要这么做吗？') # 在发送此消息后将暂停执行，等待用户的下一条消息
if confirm: # 用户发送了确认的词语
    ...

发送的消息可以为str或装有消息组件的list，如：[Plain('今日份的LittleC'), Image('https://github.com/komeiji-satori/Dress/raw/master/XxLittleCxX/0x01.jpg')]（被打

消息来源

消息组件

目前可用的有Plain（文本）、Image（图片）、Voice（语音）

别名

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

如上文，alias='m'，则使用~m xxx = ~test xxx

当为dict时则可自定义别名映射到的东西，如{'enable': 'module enable'}，则~enable xxx = ~module enable xxx

@@ 第8行： / 第8行： @@
  机器人在加载的时候会遍历<code>modules</code>文件夹，并加载每个模块文件夹里的<code>__init__.py</code>，请将想要加入的模块定义编写在<code>__init__.py</code>中或确保其能够被引用。
-当前可用的模块类型有<code>Command</code>（一般命令类型）、<code>Regex</code>（正则表达式类型）、<code>Schedule</code>（计划任务类型）、<code>StartUp</code>（自启类型）。
 == 编写 ==
@@ 第17行： / 第15行： @@
  编写模块之前，我们需要先定义一个模块类型。
-'''此定义方式目前仅支持<code>Command</code>和<code>Regex</code>模块，<code>Schedule</code>和<code>StartUp</code>请见下文的“旧版”'''
-注：Regex同理。
-==== Command ====
 <syntaxhighlight lang="python3">
-from core.component import on_command
+from core.component import module
-test = on_command(
+test = module(
     bind_prefix='test', # 定义模块名
     desc='啊吧啊吧啊吧', # 此模块的简介
@@ 第41行： / 第35行： @@
  在前文中，我们给<code>test</code>变量声明了定义，我们将围绕这个定义进行绑定子命令，为了使代码简洁，我们使用了装饰器：
-==== Command ====
+==== Command （一般命令） ====
 <syntaxhighlight lang="python3">
-from core.elements import MessageSession
+from core.builtins import Bot
-@test.handle(help_doc='<args1>', # 设置此命令的语法，前缀匹配模块名，此处忽略。可为list或tuple来经手多条命令。可为空。
+@test.command(help_doc='<args1>', # 设置此命令的语法，前缀匹配模块名，此处忽略。可为list或tuple来经手多条命令。可为空。
          required_admin = False, # 将此命令标记为仅群组管理员可使用。
          required_superuser = False, # 将此命令标记为进机器人超级管理员可使用。
          available_for = '*' # 控制此命令可被使用的消息来源，默认为 '*'（所有）
          )
-async def _(msg: MessageSession):
+async def _(msg: Bot.MessageSession):
     ...
 </syntaxhighlight>
@@ 第59行： / 第53行： @@
  如：{'<args1>': 'xxx'}
-==== Regex ====
+==== Regex （正则表达式） ====
 <syntaxhighlight lang="python3">
-from core.elements import MessageSession
+from core.builtins import Bot
-@test.handle(pattern=r'\[\[(.*?)]]', # 正则表达式语法
+@test.regex(pattern=r'\[\[(.*?)]]', # 正则表达式语法
-        mode='M', # 正则模式，设为'M'为匹配模式，'A'为匹配所有模式
+       mode='M', # 正则模式，设为'M'为匹配模式，'A'为匹配所有模式
-        flags=0, # 设置正则的flags，如Re.M|Re.I
+       flags=0, # 设置正则的flags，如Re.M|Re.I
-        show_typing=False #设置命令执行时是否展示输入提示（如戳一戳），默认为True
+       show_typing=False #设置命令执行时是否展示输入提示（如戳一戳），默认为True
          )
-async def _(msg: MessageSession):
+async def _(msg: Bot.MessageSession):
     ...
 </syntaxhighlight>
@@ 第75行： / 第69行： @@
  当你输入的命令匹配help_doc内的语法时，机器人将会把消息传入装饰器下方的函数，然后你就可以进行发挥了。
+=== Schedule（计划任务） ===
+同理。
+<syntaxhighlight lang="python3">
+from core.builtins import Bot
+from core.scheduler import CronTrigger
+@test.regex(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', '啊吧啊吧') # 向所有已开启<code>test</code>模块的用户推送消息。
+sender = 'QQ|123456' # QQ号为123456的好友
+fetch = Bot.FetchTarget.fetch_target(sender) # 获取信息
+if fetch: #如获取到
+   await fetch.sendMessage('xxx') # 发送消息
+</syntaxhighlight>
+=== 通用装饰器 ===
+假设你已经会使用了以上装饰器，而你又特别懒，则你可以使用通用装饰器来代替以上三种装饰器，此装饰器将会自动识别条件并归类函数。
+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 _():
+   ...
 === 处理消息 ===
@@ 第104行： / 第147行： @@
  当为dict时则可自定义别名映射到的东西，如<code>{'enable': 'module enable'}</code>，则~enable xxx = ~module enable xxx
-=== 旧版声明 ===
-我们在旧版命令未引入“handle”特性，使得一个装饰器只能对应一个模块，不存在绑定子命令的特性。
-此处介绍是由于时间关系，<code>Schedule</code>（计划任务类型）、<code>StartUp</code>（自启类型）尚未支持新版。
-==== Schedule ====
-<syntaxhighlight lang="python3">
-from core.component import on_schedule
-from core.elements import CronTrigger
-@on_schedule(
-     bind_prefix='test', # 定义模块名
-     trigger=CronTrigger.from_crontab('30 8 * * MON'), # 触发器
-     desc='啊吧啊吧', # 模块简介
-     alias=None, # 命令别名
-     recommend_modules=None, # 推荐打开模块
-     developers=None, # 开发者列表
-     required_superuser=False, # 是否需要超级管理员才能打开
-)
-async def weekly_rss(bot: FetchTarget):
-   ...
-</syntaxhighlight>
-===== FetchTarget =====
-主要用于从数据库中获取用户推送内容。
-<syntaxhighlight lang="python3">
-await bot.post_message('test', '啊吧啊吧') # 向所有已开启<code>test</code>模块的用户推送消息。
-sender = 'QQ|123456' # QQ号为123456的好友
-fetch = bot.fetch_target(sender) # 获取信息
-if fetch: #如获取到
-   await fetch.sendMessage('xxx') # 发送消息
-</syntaxhighlight>
 [[Category:开发]]
 {{#dpl:category=开发|mode=userformat|format=,²{#related:%PAGE%}²,,|ordermethod=lastedit}}