nonebot2/docs/guide/scheduler.md

# 添加计划任务

实际应用中还经常会有定时执行任务的需求，为了方便这类需求的开发，NoneBot 可选地包含了计划任务功能。

::: tip 提示
本章的完整代码可以在 [awesome-bot-6](https://github.com/richardchien/none-bot/tree/master/docs/guide/code/awesome-bot-6) 查看。
:::

## 安装 `scheduler` 可选功能

计划任务功能在 NoneBot 中是可选功能，只有当同时安装了 [APScheduler](https://github.com/agronholm/apscheduler) 时，才会启用。

使用下面命令安装可选功能（会自动安装 APScheduler）：

```bash
pip install none-bot[scheduler]
```

安装成功之后就可以通过 `none.scheduler` 访问 [`AsyncIOScheduler`](https://apscheduler.readthedocs.io/en/latest/modules/schedulers/asyncio.html#apscheduler.schedulers.asyncio.AsyncIOScheduler) 对象。

## 定时发送消息

这里以一个整点报时的功能为例，来介绍定时任务的使用。

新建文件 `awesome/plugins/scheduler.py`，编写代码如下：

```python {8}
from datetime import datetime

import none
import pytz
from aiocqhttp.exceptions import Error as CQHttpError


@none.scheduler.scheduled_job('cron', hour='*')
async def _():
    bot = none.get_bot()
    now = datetime.now(pytz.timezone('Asia/Shanghai'))
    try:
        await bot.send_group_msg(group_id=672076603,
                                 message=f'现在{now.hour}点整啦！')
    except CQHttpError:
        pass
```

这里最主要的就是第 8 行，`none.scheduler.scheduled_job()` 是一个装饰器，第一个参数是触发器类型（这里是 `cron`，表示使用 [Cron](https://apscheduler.readthedocs.io/en/latest/modules/triggers/cron.html#module-apscheduler.triggers.cron) 类型的触发参数）。这里 `hour='*'` 表示每小时都执行，`minute` 和 `second` 不填时默认为 `0`，也就是说装饰器所装饰的这个函数会在每小时的第一秒被执行。

除了 `cron`，还有两种触发器类型 `interval` 和 `date`。例如，你可以使用 `none.scheduler.scheduled_job('interval', minutes=10)` 来每十分钟执行一次任务。

限于篇幅，这里无法给出太详细的接口介绍，`none.scheduler` 是一个 APScheduler 的 `AsyncIOScheduler` 对象，因此关于它的更多使用方法，可以参考 [APScheduler 的官方文档](https://apscheduler.readthedocs.io/en/latest/userguide.html)。