--- sidebar_position: 2 description: 更灵活的会话控制 options: menu: - category: appendices weight: 30 --- # 会话控制 import Messenger from "@site/src/components/Messenger"; 在[指南](../tutorial/event-data.mdx#使用依赖注入)的 `weather` 插件中,我们使用依赖注入获取了机器人用户发送的地名参数,并根据地名参数进行相应的回复。但是,一问一答的对话模式仅仅适用于简单的对话场景,如果我们想要实现更复杂的对话模式,就需要使用会话控制。 ## 询问并获取用户输入 在 `weather` 插件中,我们对于用户未输入地名参数的情况直接回复了 `请输入地名` 并结束了事件流程。但是,这样用户体验并不好,需要重新输入指令和地名参数才能获取天气回复。我们现在来实现询问并获取用户地名参数的功能。 ### 询问用户 我们可以使用事件响应器操作中的 `got` 装饰器来表示当前事件处理流程需要询问并获取用户输入的消息: ```python {6} title=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` 参数存储于事件响应器状态中。 :::tip 提示 事件处理函数根据定义的顺序依次执行。 ::: ### 获取用户输入 在询问以及用户回复之后,我们就可以获取到我们需要的 `location` 参数了。我们使用 `ArgPlainText` 依赖注入来获取参数纯文本信息: ```python {9} title=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}的天气是...") ``` <Messenger msgs={[ { position: "right", msg: "/天气" }, { position: "left", msg: "请输入地名" }, { position: "right", msg: "北京" }, { position: "left", msg: "今天北京的天气是..." }, ]} /> 在上面的代码中,我们在 `got_location` 函数中定义了一个依赖注入参数 `location`,他的值将会是用户回复的消息纯文本信息。获取到用户输入的地名参数后,我们就可以进行天气查询并回复了。 :::tip 提示 如果想要获取用户回复的消息对象 `Message` ,可以使用 `Arg` 依赖注入。 ::: ### 跳过询问 在上面的代码中,如果用户在输入天气指令时,同时提供了地名参数,我们直接回复了天气信息,这部分的逻辑是和询问用户地名参数之后的逻辑一致的。如果在复杂的业务场景下,我们希望这部分代码应该复用以减少代码冗余。我们可以使用事件响应器操作中的 `set_arg` 来主动设置一个参数: ```python {4,6} title=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` 事件响应器操作来请求用户重新输入: ```python {8,9} title=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}的天气是...") ``` <Messenger msgs={[ { position: "right", msg: "/天气" }, { position: "left", msg: "请输入地名" }, { position: "right", msg: "南京" }, { position: "left", msg: "你想查询的城市 南京 暂不支持,请重新输入!" }, { position: "right", msg: "北京" }, { position: "left", msg: "今天北京的天气是..." }, ]} /> 在上面的代码中,我们在 `got_location` 函数中判断用户输入的地名是否在支持的城市列表中,如果不在,则使用 `reject` 事件响应器操作。操作将会向用户发送 `reject` 参数中的消息,并等待用户回复后,重新执行 `got_location` 函数。通过 `got` 和 `reject` 事件响应器操作,我们实现了类似于**循环**的执行方式。 `reject` 事件响应器操作与 `finish` 类似,NoneBot 会在向机器人用户发送消息内容后抛出 `RejectedException` 异常来暂停事件响应流程以等待用户输入。也就是说,在 `reject` 被执行后,后续的程序同样是不会被执行的。 ## 更多事件响应器操作 在之前的章节中,我们已经大致了解了五个事件响应器操作:`handle`、`got`、`finish`、`send` 和 `reject`。现在我们来完整地介绍一下这些操作。 事件响应器操作可以分为两大类:**交互操作**和**流程控制操作**。我们可以通过交互操作来与用户进行交互,而流程控制操作则可以用来控制事件处理流程的执行。 :::tip 提示 事件处理流程按照事件处理函数添加顺序执行,已经结束的事件处理函数不可能被恢复执行。 ::: ### handle `handle` 事件响应器操作是一个装饰器,用于向事件处理流程添加一个事件处理函数。 ```python @matcher.handle() async def handle_func(): ... ``` `handle` 装饰器支持嵌套操作,即一个事件处理函数可以被添加多次: ```python @matcher.handle() @matcher.handle() async def handle_func(): # 这个函数会被执行两次 ... ``` ### got `got` 事件响应器操作也是一个装饰器,它会在当前装饰的事件处理函数运行之前,中断当前事件处理流程,等待接收一个新的事件。它可以通过 `prompt` 参数来向用户发送询问消息,然后等待用户的回复消息,贴近对话形式会话。 `got` 装饰器接受一个参数 `key` 和一个可选参数 `prompt`。当会话状态中不存在 `key` 对应的消息时,会向用户发送 `prompt` 参数的消息,并等待用户回复。`prompt` 参数的类型和 [`send`](#send) 事件响应器操作的参数类型一致。 在事件处理函数中,可以通过依赖注入的方式来获取接收到的消息,参考:[`Arg`](../advanced/dependency.mdx#arg)、[`ArgStr`](../advanced/dependency.mdx#argstr)、[`ArgPlainText`](../advanced/dependency.mdx#argplaintext)。 ```python @matcher.got("key", prompt="请输入...") async def got_func(key: Message = Arg()): ... ``` `got` 装饰器支持与 `got` 和 `receive` 装饰器嵌套操作,即一个事件处理函数可以在接收多个事件或消息后执行: ```python @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` 不会向用户发送询问消息,并且等待一个用户事件。可以接收的事件类型取决于[会话更新](../advanced/session-updating.md)。 `receive` 装饰器接受一个可选参数 id,用于标识当前需要接收的事件,如果不指定,则默认为空 `""`。 在事件处理函数中,可以通过依赖注入的方式来获取接收到的事件,参考:[`Received`](../advanced/dependency.mdx#received)、[`LastReceived`](../advanced/dependency.mdx#lastreceived)。 ```python @matcher.receive("id") async def receive_func(event: Event = Received("id")): ... ``` `receive` 装饰器支持与 `got` 和 `receive` 装饰器嵌套操作,即一个事件处理函数可以在接收多个事件或消息后执行: ```python @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`。 ```python @matcher.handle() async def _(): await matcher.send("Hello world!") ``` ### finish 向用户回复一条消息(可选),并立即结束**整个处理流程**。 参数与 [`send`](#send) 相同。 ```python @matcher.handle() async def _(): await matcher.finish("Hello world!") # 下面的代码不会被执行 ``` ### pause 向用户回复一条消息(可选),立即结束**当前**事件处理函数,等待接收一个新的事件后进入**下一个**事件处理函数。 参数与 [`send`](#send) 相同。 ```python @matcher.handle() async def _(): if need_confirm: await matcher.pause("请在两分钟内确认执行") @matcher.handle() async def _(): ... ``` ### reject 向用户回复一条消息(可选),立即结束**当前**事件处理函数,等待接收一个新的事件后再次执行**当前**事件处理函数。 `reject` 可以用于拒绝当前 `receive` 接收的事件或 `got` 接收的参数。通常在用户回复不符合格式或标准需要重新输入,或者用于循环进行用户交互。 参数与 [`send`](#send) 相同。 ```python @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`](#send) 相同。 ```python @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`](#send) 相同。 ```python @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 立即结束当前事件处理函数,进入下一个事件处理函数。 通常在依赖注入中使用,用于跳过当前事件处理函数的执行。 ```python from nonebot.params import Depends async def dependency(): matcher.skip() @matcher.handle() async def _(check=Depends(dependency)): # 这个函数不会被执行 ``` ### stop_propagation 阻止事件向更低优先级的事件响应器传播。 ```python from nonebot.matcher import Matcher @foo.handle() async def _(matcher: Matcher): matcher.stop_propagation() ``` :::caution 注意 `stop_propagation` 操作是实例方法,需要先通过依赖注入获取事件响应器实例再进行调用。 ::: ### get_arg 获取一个 `got` 接收的参数。 `get_arg` 操作接受一个 key 参数和一个可选的 default 参数。当参数不存在时,将返回 default 或 `None`。 ```python 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 参数必须是消息序列对象,如需存储其他数据请使用[会话状态](./session-state.md)。 ```python 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`。 ```python 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`。 ```python 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 参数必须是事件对象,如需存储其他数据请使用[会话状态](./session-state.md)。 ```python from nonebot.matcher import Matcher @matcher.handle() async def _(matcher: Matcher): matcher.set_receive("key", Event()) ```