diff --git a/docs/api/plugin.md b/docs/api/plugin.md index 7aeeabc9..42cdf84f 100644 --- a/docs/api/plugin.md +++ b/docs/api/plugin.md @@ -346,6 +346,50 @@ sidebarDepth: 0 +## `on_keyword(keywords, rule=None, **kwargs)` + + +* **说明** + + 注册一个消息事件响应器,并且当消息纯文本部分包含关键词时响应。 + + + +* **参数** + + + * `keywords: Set[str]`: 关键词列表 + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `permission: Optional[Permission]`: 事件响应权限 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器(仅执行一次) + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + ## `on_command(cmd, rule=None, aliases=None, **kwargs)` diff --git a/docs/api/rule.md b/docs/api/rule.md index 9142ce2e..dade2a5b 100644 --- a/docs/api/rule.md +++ b/docs/api/rule.md @@ -123,7 +123,7 @@ Rule(async_function, run_sync(sync_function)) -## `keyword(msg)` +## `keyword(*keywords)` * **说明** @@ -135,7 +135,7 @@ Rule(async_function, run_sync(sync_function)) * **参数** - * `msg: str`: 关键词 + * `*keywords: str`: 关键词 @@ -175,7 +175,9 @@ Rule(async_function, run_sync(sync_function)) * **说明** - 根据正则表达式进行匹配 + 根据正则表达式进行匹配。 + + 可以通过 `state["_matched"]` 获取正则表达式匹配成功的文本。 diff --git a/nonebot/plugin.py b/nonebot/plugin.py index b0196bd2..32be4dbc 100644 --- a/nonebot/plugin.py +++ b/nonebot/plugin.py @@ -16,7 +16,7 @@ from nonebot.log import logger from nonebot.matcher import Matcher from nonebot.permission import Permission from nonebot.typing import Handler, RuleChecker -from nonebot.rule import Rule, startswith, endswith, command, regex +from nonebot.rule import Rule, startswith, endswith, keyword, command, regex from nonebot.typing import Any, Set, List, Dict, Type, Tuple, Union, Optional, ModuleType plugins: Dict[str, "Plugin"] = {} @@ -232,8 +232,7 @@ def on_startswith(msg: str, :返回: - ``Type[Matcher]`` """ - return on_message(startswith(msg) & rule, **kwargs) if rule else on_message( - startswith(msg), **kwargs) + return on_message(startswith(msg) & rule, **kwargs) def on_endswith(msg: str, @@ -254,8 +253,28 @@ def on_endswith(msg: str, :返回: - ``Type[Matcher]`` """ - return on_message(endswith(msg) & rule, **kwargs) if rule else on_message( - startswith(msg), **kwargs) + return on_message(endswith(msg) & rule, **kwargs) + + +def on_keyword(keywords: Set[str], + rule: Optional[Union[Rule, RuleChecker]] = None, + **kwargs) -> Type[Matcher]: + """ + :说明: + 注册一个消息事件响应器,并且当消息纯文本部分包含关键词时响应。 + :参数: + * ``keywords: Set[str]``: 关键词列表 + * ``rule: Optional[Union[Rule, RuleChecker]]``: 事件响应规则 + * ``permission: Optional[Permission]``: 事件响应权限 + * ``handlers: Optional[List[Handler]]``: 事件处理函数列表 + * ``temp: bool``: 是否为临时事件响应器(仅执行一次) + * ``priority: int``: 事件响应器优先级 + * ``block: bool``: 是否阻止事件向更低优先级传递 + * ``state: Optional[dict]``: 默认的 state + :返回: + - ``Type[Matcher]`` + """ + return on_message(keyword(*keywords) & rule, **kwargs) def on_command(cmd: Union[str, Tuple[str, ...]], @@ -290,9 +309,7 @@ def on_command(cmd: Union[str, Tuple[str, ...]], handlers.insert(0, _strip_cmd) commands = set([cmd]) | (aliases or set()) - return on_message(command(*commands) & rule, handlers=handlers, ** - kwargs) if rule else on_message( - command(*commands), handlers=handlers, **kwargs) + return on_message(command(*commands) & rule, handlers=handlers, **kwargs) def on_regex(pattern: str, @@ -317,9 +334,7 @@ def on_regex(pattern: str, :返回: - ``Type[Matcher]`` """ - return on_message(regex(pattern, flags) & - rule, **kwargs) if rule else on_message( - regex(pattern, flags), **kwargs) + return on_message(regex(pattern, flags) & rule, **kwargs) class CommandGroup: diff --git a/nonebot/plugin.pyi b/nonebot/plugin.pyi index dbd96365..6cf93b97 100644 --- a/nonebot/plugin.pyi +++ b/nonebot/plugin.pyi @@ -69,8 +69,8 @@ def on_request(rule: Optional[Union[Rule, RuleChecker]] = ..., def on_startswith(msg: str, rule: Optional[Optional[Union[Rule, RuleChecker]]] = ..., - permission: Optional[Permission] = ..., *, + permission: Optional[Permission] = ..., handlers: Optional[List[Handler]] = ..., temp: bool = ..., priority: int = ..., @@ -81,8 +81,8 @@ def on_startswith(msg: str, def on_endswith(msg: str, rule: Optional[Optional[Union[Rule, RuleChecker]]] = ..., - permission: Optional[Permission] = ..., *, + permission: Optional[Permission] = ..., handlers: Optional[List[Handler]] = ..., temp: bool = ..., priority: int = ..., @@ -91,11 +91,23 @@ def on_endswith(msg: str, ... +def on_keyword(keywords: Set[str], + rule: Optional[Optional[Union[Rule, RuleChecker]]] = ..., + *, + permission: Optional[Permission] = ..., + handlers: Optional[List[Handler]] = ..., + temp: bool = ..., + priority: int = ..., + block: bool = ..., + state: Optional[dict] = ...) -> Type[Matcher]: + ... + + def on_command(cmd: Union[str, Tuple[str, ...]], rule: Optional[Union[Rule, RuleChecker]] = ..., aliases: Optional[Set[Union[str, Tuple[str, ...]]]] = ..., - permission: Optional[Permission] = ..., *, + permission: Optional[Permission] = ..., handlers: Optional[List[Handler]] = ..., temp: bool = ..., priority: int = ..., @@ -107,8 +119,8 @@ def on_command(cmd: Union[str, Tuple[str, ...]], def on_regex(pattern: str, flags: Union[int, re.RegexFlag] = 0, rule: Optional[Rule] = ..., - permission: Optional[Permission] = ..., *, + permission: Optional[Permission] = ..., handlers: Optional[List[Handler]] = ..., temp: bool = ..., priority: int = ..., diff --git a/nonebot/rule.py b/nonebot/rule.py index c950c449..faefbd76 100644 --- a/nonebot/rule.py +++ b/nonebot/rule.py @@ -182,16 +182,17 @@ def endswith(msg: str) -> Rule: return Rule(_endswith) -def keyword(msg: str) -> Rule: +def keyword(*keywords: str) -> Rule: """ :说明: 匹配消息关键词 :参数: - * ``msg: str``: 关键词 + * ``*keywords: str``: 关键词 """ async def _keyword(bot: Bot, event: Event, state: dict) -> bool: - return bool(event.plain_text and msg in event.plain_text) + return bool(event.plain_text and + any(keyword in event.plain_text for keyword in keywords)) return Rule(_keyword) @@ -240,7 +241,7 @@ def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule: """ :说明: 根据正则表达式进行匹配。 - + 可以通过 ``state["_matched"]`` 获取正则表达式匹配成功的文本。 :参数: * ``regex: str``: 正则表达式 @@ -261,6 +262,7 @@ def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule: else: state["_matched"] = None return False + return Rule(_regex)