mirai-core-api/net.mamoe.mirai.event/EventHandler

EventHandler

@Target(allowedTargets = [AnnotationTarget.FUNCTION])

annotation class EventHandler( val priority: EventPriority = EventPriority.NORMAL, val ignoreCancelled: Boolean = true, val concurrency: ConcurrencyKind = ConcurrencyKind.CONCURRENT)

标注一个函数为事件监听器.

Kotlin 函数

Kotlin 函数要求:

接收者和函数参数: 所标注的 Kotlin 函数必须至少拥有一个接收者或一个函数参数, 或二者都具有. 接收者和函数参数的类型必须相同 (如果二者都存在) 接收者或函数参数的类型都必须为 Event 或其子类.
返回值: 为 Unit 或不指定返回值时将注册为 EventChannel.subscribeAlways, 为 ListeningStatus 时将注册为 EventChannel.subscribe. 任何其他类型的返回值将会在注册时抛出异常.

所有 Kotlin 非 suspend 的函数都将会在 Dispatchers.IO 中调用

支持的函数类型:

// 所有函数参数, 函数返回值都不允许标记为可空 (带有 '?' 符号)
// T 表示任何 Event 类型.
suspend fun T.onEvent(T)
suspend fun T.onEvent(T): ListeningStatus
suspend fun T.onEvent(T): Nothing
suspend fun onEvent(T)
suspend fun onEvent(T): ListeningStatus
suspend fun onEvent(T): Nothing
suspend fun T.onEvent()
suspend fun T.onEvent(): ListeningStatus
suspend fun T.onEvent(): Nothing
fun T.onEvent(T)
fun T.onEvent(T): ListeningStatus
fun T.onEvent(T): Nothing
fun onEvent(T)
fun onEvent(T): ListeningStatus
fun onEvent(T): Nothing
fun T.onEvent()
fun T.onEvent(): ListeningStatus
fun T.onEvent(): Nothing

Kotlin 使用示例:

独立 CoroutineScope 和 ListenerHost

object MyEvents : ListenerHost {
    override val coroutineContext = SupervisorJob()


    // 可以抛出任何异常, 将在 this.coroutineContext 或 registerEvents 时提供的 CoroutineScope.coroutineContext 中的 CoroutineExceptionHandler 处理.
    @EventHandler
    suspend fun MessageEvent.onMessage() {
        reply("received")
    }
}

myCoroutineScope.registerEvents(MyEvents)

onMessage 抛出的异常将会交给 myCoroutineScope 处理

合并 CoroutineScope 和 ListenerHost: 使用 SimpleListenerHost

object MyEvents : SimpleListenerHost( /* override coroutineContext here */) {
    override fun handleException(context: CoroutineContext, exception: Throwable) {
        // 处理 onMessage 中未捕获的异常
    }

    @EventHandler
    suspend fun MessageEvent.onMessage() { // 可以抛出任何异常, 将在 handleException 处理
        reply("received")
        // 无返回值 (或者返回 Unit), 表示一直监听事件.
    }

    @EventHandler
    suspend fun MessageEvent.onMessage(): ListeningStatus { // 可以抛出任何异常, 将在 handleException 处理
        reply("received")

        return ListeningStatus.LISTENING // 表示继续监听事件
        // return ListeningStatus.STOPPED // 表示停止监听事件
    }
}

MyEvents.registerTo(eventChannel)
// 或 eventChannel.registerListenerHost(MyEvents)

Java 方法

所有 Java 方法都会在 Dispatchers.IO 中调用.

支持的方法类型

// T 表示任何 Event 类型.
void onEvent(T)
Void onEvent(T)
@NotNull ListeningStatus onEvent(T) // 禁止返回 null

Java 使用示例:

public class MyEventHandlers extends SimpleListenerHost {
    @Override
    public void handleException(@NotNull CoroutineContext context, @NotNull Throwable exception){
        // 处理事件处理时抛出的异常
    }

    @EventHandler
    public void onMessage(@NotNull MessageEvent event) throws Exception { // 可以抛出任何异常, 将在 handleException 处理
        event.subject.sendMessage("received");
        // 无返回值, 表示一直监听事件.
    }

    @NotNull
    @EventHandler
    public ListeningStatus onMessage(@NotNull MessageEvent event) throws Exception { // 可以抛出任何异常, 将在 handleException 处理
        event.subject.sendMessage("received");

        return ListeningStatus.LISTENING; // 表示继续监听事件
        // return ListeningStatus.STOPPED; // 表示停止监听事件
    }
}

eventChannel.registerListenerHost(new MyEventHandlers())

//@sample net.mamoe.mirai.event.JvmMethodEventsTest

Constructors

EventHandler

fun EventHandler( priority: EventPriority = EventPriority.NORMAL, ignoreCancelled: Boolean = true, concurrency: ConcurrencyKind = ConcurrencyKind.CONCURRENT)

Properties

concurrency

val concurrency: ConcurrencyKind

并发类型

ignoreCancelled

val ignoreCancelled: Boolean = true

是否自动忽略被取消

priority

val priority: EventPriority

监听器优先级