Version: 2.0.0rc4

会话控制

在指南的 weather 插件中，我们使用依赖注入获取了机器人用户发送的地名参数，并根据地名参数进行相应的回复。但是，一问一答的对话模式仅仅适用于简单的对话场景，如果我们想要实现更复杂的对话模式，就需要使用会话控制。

询问并获取用户输入

在 weather 插件中，我们对于用户未输入地名参数的情况直接回复了 请输入地名 并结束了事件流程。但是，这样用户体验并不好，需要重新输入指令和地名参数才能获取天气回复。我们现在来实现询问并获取用户地名参数的功能。

询问用户

我们可以使用事件响应器操作中的 got 装饰器来表示当前事件处理流程需要询问并获取用户输入的消息：

weather/__init__.py
@weather.handle()
async def handle_function(args: Message = CommandArg()):
    if location := args.extract_plain_text():
        await weather.finish(f"今天{location}的天气是...")


@weather.got("location", prompt="请输入地名")
async def got_location():
    ...

在上面的代码中，我们使用 got 事件响应器操作来向用户发送 prompt 消息，并等待用户的回复。用户的回复消息将会被作为 location 参数存储于事件响应器状态中。

提示

事件处理函数根据定义的顺序依次执行。

获取用户输入

在询问以及用户回复之后，我们就可以获取到我们需要的 location 参数了。我们使用 ArgPlainText 依赖注入来获取参数纯文本信息：

weather/__init__.py
from nonebot.params import ArgPlainText


@weather.handle()
async def handle_function(args: Message = CommandArg()):
    if location := args.extract_plain_text():
        await weather.finish(f"今天{location}的天气是...")


@weather.got("location", prompt="请输入地名")
async def got_location(location: str = ArgPlainText()):
    await weather.finish(f"今天{location}的天气是...")
NoneBot
/天气
NoneBotNoneBot
请输入地名
北京
NoneBotNoneBot
今天北京的天气是...

在上面的代码中，我们在 got_location 函数中定义了一个依赖注入参数 location，他的值将会是用户回复的消息纯文本信息。获取到用户输入的地名参数后，我们就可以进行天气查询并回复了。

提示

如果想要获取用户回复的消息对象 Message ，可以使用 Arg 依赖注入。

跳过询问

在上面的代码中，如果用户在输入天气指令时，同时提供了地名参数，我们直接回复了天气信息，这部分的逻辑是和询问用户地名参数之后的逻辑一致的。如果在复杂的业务场景下，我们希望这部分代码应该复用以减少代码冗余。我们可以使用事件响应器操作中的 set_arg 来主动设置一个参数：

weather/__init__.py
from nonebot.matcher import Matcher


@weather.handle()
async def handle_function(matcher: Matcher, args: Message = CommandArg()):
    if args.extract_plain_text():
        matcher.set_arg("location", args)


@weather.got("location", prompt="请输入地名")
async def got_location(location: str = ArgPlainText()):
    await weather.finish(f"今天{location}的天气是...")

请注意，设置参数需要使用依赖注入来获取 Matcher 实例以确保上下文正确，且参数值应为 Message 对象。

在 location 参数被设置之后，got 事件响应器操作将不再会询问并等待用户的回复，而是直接进入 got_location 函数。

请求重新输入

在实际的业务场景中，用户的输入很有可能并非是我们所期望的，而结束事件处理流程让用户重新发送指令也不是一个好的体验。这时我们可以使用 reject 事件响应器操作来请求用户重新输入：

weather/__init__.py
@weather.handle()
async def handle_function(matcher: Matcher, args: Message = CommandArg()):
    if args.extract_plain_text():
        matcher.set_arg("location", args)


@weather.got("location", prompt="请输入地名")
async def got_location(location: str = ArgPlainText()):
    if location not in ["北京", "上海", "广州", "深圳"]:
        await weather.reject(f"你想查询的城市 {location} 暂不支持，请重新输入！")
    await weather.finish(f"今天{location}的天气是...")
NoneBot
/天气
NoneBotNoneBot
请输入地名
南京
NoneBotNoneBot
你想查询的城市 南京 暂不支持，请重新输入！
北京
NoneBotNoneBot
今天北京的天气是...

在上面的代码中，我们在 got_location 函数中判断用户输入的地名是否在支持的城市列表中，如果不在，则使用 reject 事件响应器操作。操作将会向用户发送 reject 参数中的消息，并等待用户回复后，重新执行 got_location 函数。通过 got 和 reject 事件响应器操作，我们实现了类似于循环的执行方式。

reject 事件响应器操作与 finish 类似，NoneBot 会在向机器人用户发送消息内容后抛出 RejectedException 异常来暂停事件响应流程以等待用户输入。也就是说，在 reject 被执行后，后续的程序同样是不会被执行的。

更多事件响应器操作

在之前的章节中，我们已经大致了解了五个事件响应器操作：handle、got、finish、send 和 reject。现在我们来完整地介绍一下这些操作。

事件响应器操作可以分为两大类：交互操作和流程控制操作。我们可以通过交互操作来与用户进行交互，而流程控制操作则可以用来控制事件处理流程的执行。

提示

事件处理流程按照事件处理函数添加顺序执行，已经结束的事件处理函数不可能被恢复执行。

handle

handle 事件响应器操作是一个装饰器，用于向事件处理流程添加一个事件处理函数。

@matcher.handle()
async def handle_func():
    ...

handle 装饰器支持嵌套操作，即一个事件处理函数可以被添加多次：

@matcher.handle()
@matcher.handle()
async def handle_func():
    # 这个函数会被执行两次
    ...

got

got 事件响应器操作也是一个装饰器，它会在当前装饰的事件处理函数运行之前，中断当前事件处理流程，等待接收一个新的事件。它可以通过 prompt 参数来向用户发送询问消息，然后等待用户的回复消息，贴近对话形式会话。

got 装饰器接受一个参数 key 和一个可选参数 prompt。当会话状态中不存在 key 对应的消息时，会向用户发送 prompt 参数的消息，并等待用户回复。prompt 参数的类型和 send 事件响应器操作的参数类型一致。

在事件处理函数中，可以通过依赖注入的方式来获取接收到的消息，参考：Arg、ArgStr、ArgPlainText。

@matcher.got("key", prompt="请输入...")
async def got_func(key: Message = Arg()):
    ...

got 装饰器支持与 got 和 receive 装饰器嵌套操作，即一个事件处理函数可以在接收多个事件或消息后执行：

@matcher.got("key1", prompt="请输入key1...")
@matcher.got("key2", prompt="请输入key2...")
@matcher.receive("key3")
async def got_func(key1: Message = Arg(), key2: Message = Arg(), key3: Event = Received("key3")):
    ...

receive

receive 事件响应器操作也是一个装饰器，它会在当前装饰的事件处理函数运行之前，中断当前事件处理流程，等待接收一个新的事件。与 got 不同的是，receive 不会向用户发送询问消息，并且等待一个用户事件。可以接收的事件类型取决于会话更新。

receive 装饰器接受一个可选参数 id，用于标识当前需要接收的事件，如果不指定，则默认为空 ""。

在事件处理函数中，可以通过依赖注入的方式来获取接收到的事件，参考：Received、LastReceived。

@matcher.receive("id")
async def receive_func(event: Event = Received("id")):
    ...

receive 装饰器支持与 got 和 receive 装饰器嵌套操作，即一个事件处理函数可以在接收多个事件或消息后执行：

@matcher.receive("key1")
@matcher.got("key2", prompt="请输入key2...")
@matcher.got("key3", prompt="请输入key3...")
async def receive_func(key1: Event = Received("key1"), key2: Message = Arg(), key3: Message = Arg()):
    ...

send

send 事件响应器操作用于向用户回复一条消息。协议适配器会根据当前 event 选择回复的途径。

send 操作接受一个参数 message 和其他任何协议适配器接受的参数。message 参数类型可以是字符串、消息序列、消息段或者消息模板。消息模板将会使用会话状态字典进行渲染后发送。

这个操作等同于使用 bot.send(event, message, **kwargs)，但不需要自行传入 event。

@matcher.handle()
async def _():
    await matcher.send("Hello world!")

finish

向用户回复一条消息（可选），并立即结束整个处理流程。

参数与 send 相同。

@matcher.handle()
async def _():
    await matcher.finish("Hello world!")
    # 下面的代码不会被执行

pause

向用户回复一条消息（可选），立即结束当前事件处理函数，等待接收一个新的事件后进入下一个事件处理函数。

参数与 send 相同。

@matcher.handle()
async def _():
    if need_confirm:
        await matcher.pause("请在两分钟内确认执行")


@matcher.handle()
async def _():
    ...

reject

向用户回复一条消息（可选），立即结束当前事件处理函数，等待接收一个新的事件后再次执行当前事件处理函数。

reject 可以用于拒绝当前 receive 接收的事件或 got 接收的参数。通常在用户回复不符合格式或标准需要重新输入，或者用于循环进行用户交互。

参数与 send 相同。

@matcher.got("arg")
async def _(arg: str = ArgPlainText()):
    if not is_valid(arg):
        await matcher.reject("Invalid arg!")

reject_arg

向用户回复一条消息（可选），立即结束当前事件处理函数，等待接收一个新的消息后再次执行当前事件处理函数。

reject_arg 用于拒绝指定 got 接收的参数，通常在嵌套装饰器时使用。

reject_arg 操作接受一个 key 参数以及可选的 prompt 参数。prompt 参数与 send 相同。

@matcher.got("a")
@matcher.got("b")
async def _(a: str = ArgPlainText(), b: str = ArgPlainText()):
    if a not in b:
        await matcher.reject_arg("a", "Invalid a!")

reject_receive

向用户回复一条消息（可选），立即结束当前事件处理函数，等待接收一个新的事件后再次执行当前事件处理函数。

reject_receive 用于拒绝指定 receive 接收的事件，通常在嵌套装饰器时使用。

reject_receive 操作接受一个可选的 id 参数以及可选的 prompt 参数。id 参数默认为空 ""，prompt 参数与 send 相同。

@matcher.receive("a")
@matcher.receive("b")
async def _(a: Event = Received("a"), b: Event = Received("b")):
    if a.get_user_id() != b.get_user_id():
        await matcher.reject_receive("a")

skip

立即结束当前事件处理函数，进入下一个事件处理函数。

通常在依赖注入中使用，用于跳过当前事件处理函数的执行。

from nonebot.params import Depends


async def dependency():
    matcher.skip()


@matcher.handle()
async def _(check=Depends(dependency)):
    # 这个函数不会被执行

stop_propagation

阻止事件向更低优先级的事件响应器传播。

from nonebot.matcher import Matcher


@foo.handle()
async def _(matcher: Matcher):
    matcher.stop_propagation()
注意

stop_propagation 操作是实例方法，需要先通过依赖注入获取事件响应器实例再进行调用。

get_arg

获取一个 got 接收的参数。

get_arg 操作接受一个 key 参数和一个可选的 default 参数。当参数不存在时，将返回 default 或 None。

from nonebot.matcher import Matcher


@matcher.handle()
async def _(matcher: Matcher):
    key = matcher.get_arg("key", default=None)

set_arg

设置 / 覆盖一个 got 接收的参数。

set_arg 操作接受一个 key 参数和一个 value 参数。请注意，value 参数必须是消息序列对象，如需存储其他数据请使用会话状态。

from nonebot.matcher import Matcher


@matcher.handle()
async def _(matcher: Matcher):
    matcher.set_arg("key", Message("value"))

get_receive

获取一个 receive 接收的事件。

get_receive 操作接受一个 id 参数和一个可选的 default 参数。当事件不存在时，将返回 default 或 None。

from nonebot.matcher import Matcher


@matcher.handle()
async def _(matcher: Matcher):
    event = matcher.get_receive("id", default=None)

get_last_receive

获取最近的一个 receive 接收的事件。

get_last_receive 操作接受一个可选的 default 参数。当事件不存在时，将返回 default 或 None。

from nonebot.matcher import Matcher


@matcher.handle()
async def _(matcher: Matcher):
    event = matcher.get_last_receive(default=None)

set_receive

设置 / 覆盖一个 receive 接收的事件。

set_receive 操作接受一个 id 参数和一个 event 参数。请注意，event 参数必须是事件对象，如需存储其他数据请使用会话状态。

from nonebot.matcher import Matcher


@matcher.handle()
async def _(matcher: Matcher):
    matcher.set_receive("key", Event())