# 自定义过滤规则
>[info] 核心`1.8.0`版本后支持使用者自定义并使用一些过滤规则。
如果`@Filter`注解中的参数无法满足你繁杂的过滤规则,那么你可以来看看如何自定义一套过滤规则并使用它们。
>[warning] 自定义过滤规则的优先级位于`@Filter`所有自带过滤规则之后,只有当`@Filter`自带的规则全部通过之后才会触发后续规则。
## **自定义过滤接口**
首先,你需要写一个类并实现`com.forte.qqrobot.listener.Filterable` 接口,并实现其中的方法:
```java
/**
* 根据自定义规则对消息进行过滤
* @param filter filter注解对象
* @param msgget 接收到的消息
* @param at 判断当前消息是否被at的函数
* @return 是否通过
*/
boolean filter(Filter filter, MsgGet msgget, AtDetection at);
```
>[danger] `AtDetection`在核心`1.8.0`中存在bug无法使用,`1.8.1`中被修复。
当过滤规则被触发的时候,参数中`filter`即为当前监听函数上存在的`@Filter`注解,`msgget`即为当前接收到的消息,`at`则可以通过`test()`方法来判断当前方法中是否at了机器人自身。*不过最保险的方法还是直接使用字符串判断。* 而方法的返回值即代表了是否放行此次过滤。如果不放行,则后续的过滤器不会被触发,监听函数也不会被触发。
其中,返回值`true`代表放行,`false`代表不放行。
## **注册自定义过滤**
你有两种方式来注册一个自定义过滤。
>[warning] 无论使用哪种方法注入,都需要先实现`Filterable`接口。
### **自动注册**
你可以写一个实现了`Filterable`接口的实现类,并将其注入依赖中心。之后,框架会在启动的时候自动搜寻以被注入的所有`Filterable`实现类并自动注册。
>[info] 前提是此类能够被扫描到。
* 你可以选择使用`@Beans`进行注入,被注入的自定义过滤的名称就是类名的开头小写。
* 你可以选择使用`@DIYFilter`进行注入,`@DIYFilter`存在一个`value`参数,如果这个参数不填,则效果与`@Beans`相同,如果填了,那么注册的这个自定义过滤的名称就与你所填写的参数一致。
举个栗子:
#### **@Beans**
```java
@Beans
public class TestFilter2 implements Filterable {
@Override
public boolean filter(Filter filter, MsgGet msgget, AtDetection at) {
return true;
}
}
```
>[warning] 1.9.0更新后,接口参数变成了:`filter(Filter filter, MsgGet msgget, AtDetection at, ListenContext context);`
#### **@DIYFilter**
```java
@DIYFilter("filter2")
public class TestFilter2 implements Filterable {
@Override
public boolean filter(Filter filter, MsgGet msgget, AtDetection at) {
return true;
}
}
```
### **手动注册**
除了自动注册以外,我还提供了一个手动注册的方法,就是使用`ListenerFilter`类的静态方法`registerFilter`来注册一个自定义过滤:
```java
ListenerFilter.registerFilter("TEST_FILTER3", new TestFilter3());
ListenerFilter.registerFilter("TEST_FILTER4", (filter, msg, at, context) -> true);
```
很显而易见的,第一个参数即为名称,而第二个就是实例对象或者一个lambda表达式了。
>[danger] 无论任何方法,如果注册的监听函数出现了名称冲突,会抛出异常。
## **使用自定义过滤**
注册好了自定义过滤,该如何使用呢?直接在`@Filter`的参数`diyFilter`中填入你所注册的自定义过滤器的名称即可。
如果你填了多个名称,你可以使用`mostDIYType`参数来决定它们的匹配规则。
例如:
```java
@Listen(MsgGetTypes.privateMsg)
@Filter(diyFilter = "TEST_FILTER3")
public void run(PrivateMsg privateMsg){
// todo something...
}
```
>[info] `mostDIYType`参数是类型为`MostDIYType`的枚举类型,可以至[枚举章节](./枚举.md)查找。
- 前言
- 简单介绍
- 我该如何阅读文档
- 视频教程
- 安装与使用
- 开源协议
- 免责&捐助
- 注意事项
- 版本命名规则简介
- 主要功能版本历史
- 功能指引
- 通用API与功能
- 国际化语言
- 异常
- 消息监听
- @Listen
- @OnListen模板
- @Filter
- 消息参数截取
- @Spare
- @Constr
- @Ignore
- @ListenBreak
- @ListenBreakPlugin
- @ListenBody
- 监听响应
- 成功判定与返回值
- 监听上下文
- 动态参数
- 监听消息API
- 异步监听 @Async
- 限流监听 @Limit
- 自定义Http送信器
- 枚举与类型
- 送信器
- SENDER
- SETTER
- GETTER
- 返回值
- 其他位置
- 日志与日志拦截
- 异常处理
- 依赖注入
- 自定义依赖获取
- 批量依赖载入
- 注意事项
- 常量
- 定时任务
- 自定义过滤
- 拦截器
- 拦截器总定义
- 上下文对象总定义
- 监听消息拦截
- 送信器拦截
- 监听函数拦截
- CAT码
- CQ码
- CQCode
- CQ码工具类
- CQ扩展工具类
- AppendList拼接链
- 高级内容
- 阻断机制
- 截断机制
- 自定义枚举类型
- 枚举工厂
- byName注解
- 自定义注解
- 配置
- 文件配置
- 注解配置
- 参数配置
- 多配置
- 多账号
- 自定义账号管理器
- 小心!
- 核心版本与组件如何升级核心
- 核心版本迭代指南
- 核心
- 更新日志
- jar包与依赖
- 监听消息类结构图
- 快速启动
- 模组与扩展
- 模组开发
- 现有模组
- 通用模组-延时任务
- 通用模组-CQ码工具
- 转义器
- CQ码操作工具类
- CQ码模板-CodeTemplate
- CQ码载体-KQCode
- CQ码构建器
- MQ码工具类
- 通用模组-redis-bot管理器
- 通用模组-Debugger
- Debugger-common模块
- Debugger-server模块
- Debugger-client模块
- 通用模组-钉钉机器人
- 组件-Mirai(JVM)
- 快速开始(1.13+)
- springboot-starter
- 注意事项
- 配置
- 额外的内容
- 快速回复
- 额外监听
- CQ码解析
- 组件-酷Q(QQ)-CQ HTTP API(基本失效)
- 快速开始(推荐)
- 快速开始(1.7.x以下,不推荐)
- 快速开始(Springboot启动器)
- 启动器、启动接口与配置类
- 配置
- 文件配置
- 注意事项
- 更新日志
- 额外的内容
- 自定义额外监听
- CQ送信器
- 元事件
- 监听消息类结构图
- 组件-酷Q(QQ)-JCQ(失效)
- 快速开始
- 更新日志
- 额外的内容
- JCQ日志
- 配置
- 注意事项
- 监听消息类结构图
- 组件-酷Q(QQ)-HTTP TO CQ(失效)
- 快速开始(核心1.7.x及以下)
- 启动器、启动接口与配置类
- 配置
- 文件配置
- 注意事项
- 更新日志
- 监听消息类结构图
- 组件-酷Q(QQ)-LEMOC (失效)
- 快速开始(核心1.7.x及以下)
- 配置
- 注意事项
- 更新日志
- 监听消息类结构图
- Springboot快速启动器
- 常见问题汇总
- BUG反馈
- 更新计划总览