事件系统

Assiah 提供 12 个 Bukkit 事件，覆盖邮件的完整生命周期。标记 ✅ 的事件可取消。

事件一览

事件	可取消	说明
MailSendEvent	✅	邮件发送前触发
MailDeliveredEvent	❌	邮件投递完成后触发
MailReadEvent	❌	邮件阅读状态变更时触发
MailClaimEvent	❌	邮件附件领取后触发
MailDeleteEvent	❌	邮件被删除时触发
MailArchiveEvent	❌	邮件被归档时触发
MailReplyEvent	❌	邮件被回复时触发
MailForwardEvent	❌	邮件被转发时触发
MailDraftSaveEvent	❌	草稿被保存时触发
MailTemplateSaveEvent	✅	模板保存前触发
MailTemplateApplyEvent	✅	模板应用到草稿前触发
MailTemplateDeleteEvent	✅	模板删除前触发

基类

MailEvent

邮件事件基类，继承自 BukkitProxyEvent。所有与已存在邮件相关的事件均继承此类。

属性	类型	说明
ownerId	UUID	邮件所有者 UUID
mail	MailSummary	触发事件的邮件摘要

事件详情

MailSendEvent

邮件发送前触发，取消后邮件不会发送。继承 MailEvent。

属性	类型	说明
ownerId	UUID	邮件所有者 UUID
mail	MailSummary	邮件摘要（发送前的预览快照）
sender	SenderSnapshot	发送者快照
recipient	Recipient	收件人信息

@SubscribeEvent
fun onMailSend(event: MailSendEvent) {
    // 禁止向某个玩家发送邮件
    if (event.recipient.uuid == bannedUUID) {
        event.isCancelled = true
    }
}

MailDeliveredEvent

邮件成功投递到收件箱后触发。继承 MailEvent。

属性	类型	说明
ownerId	UUID	收件人 UUID
mail	MailSummary	邮件摘要

@SubscribeEvent
fun onMailDelivered(event: MailDeliveredEvent) {
    val player = Bukkit.getPlayer(event.ownerId)
    player?.sendMessage("你收到了一封新邮件：${event.mail.title}")
}

MailReadEvent

邮件阅读状态变更时触发（标记已读或标记未读）。继承 MailEvent。

属性	类型	说明
ownerId	UUID	邮箱所有者 UUID
mail	MailSummary	邮件摘要
read	Boolean	变更后的阅读状态，true 已读，false 未读

MailClaimEvent

邮件附件领取后触发（无论成功或失败）。继承 MailEvent。

属性	类型	说明
ownerId	UUID	领取者 UUID
mail	MailSummary	邮件摘要
success	Boolean	领取是否成功

MailDeleteEvent

邮件被删除时触发。继承 MailEvent。

属性	类型	说明
ownerId	UUID	邮箱所有者 UUID
mail	MailSummary	邮件摘要
forced	Boolean	是否为强制删除（管理员操作），默认 false

MailArchiveEvent

邮件被归档时触发。继承 MailEvent。

属性	类型	说明
ownerId	UUID	邮箱所有者 UUID
mail	MailSummary	邮件摘要
forced	Boolean	是否为强制归档（管理员操作），默认 false

MailReplyEvent

邮件被回复并成功创建回复邮件后触发。继承 MailEvent。

属性	类型	说明
ownerId	UUID	回复者 UUID
mail	MailSummary	新创建的回复邮件摘要
requestMail	Mail	被回复的原始邮件完整信息

MailForwardEvent

邮件被转发并成功创建转发邮件后触发。继承 MailEvent。

属性	类型	说明
ownerId	UUID	转发者 UUID
mail	MailSummary	新创建的转发邮件摘要
requestMail	Mail	被转发的原始邮件完整信息

MailDraftSaveEvent

草稿被保存时触发。独立于 MailEvent 体系，直接继承 BukkitProxyEvent。

属性	类型	说明
owner	UUID	草稿所有者 UUID
draft	MailDraft	保存后的草稿对象
autoSave	Boolean	是否为自动保存触发

MailTemplateSaveEvent

模板保存前触发，取消后模板不会保存。直接继承 BukkitProxyEvent。

属性	类型	说明
owner	UUID	操作者 UUID
template	MailTemplate	即将保存的模板对象
fromDraftId	String	来源草稿 ID

MailTemplateApplyEvent

模板应用到草稿前触发，取消后模板不会应用。直接继承 BukkitProxyEvent。

属性	类型	说明
owner	UUID	操作者 UUID
template	MailTemplate	即将应用的模板对象
targetDraftId	String	目标草稿 ID

MailTemplateDeleteEvent

模板删除前触发，取消后模板不会删除。直接继承 BukkitProxyEvent。

属性	类型	说明
owner	UUID	操作者 UUID
template	MailTemplate	即将删除的模板对象

监听示例

import taboolib.common.platform.event.SubscribeEvent

class AssiahListener {

    @SubscribeEvent
    fun onSend(event: MailSendEvent) {
        // 记录邮件发送日志
        logger.info("${event.sender.name} -> ${event.recipient.name}: ${event.mail.title}")
    }

    @SubscribeEvent
    fun onClaim(event: MailClaimEvent) {
        // 记录附件领取
        if (event.success) {
            logger.info("${event.ownerId} 领取了邮件 ${event.mail.mailId} 的附件")
        }
    }

    @SubscribeEvent
    fun onTemplateSave(event: MailTemplateSaveEvent) {
        // 阻止保存全局模板
        if (event.template.global) {
            event.isCancelled = true
        }
    }
}

备注

所有事件位于 kim.hhhhhy.assiah.api.event 包下。继承 MailEvent 的事件通过 ownerId 和 mail 属性访问邮件信息；模板和草稿事件直接继承 BukkitProxyEvent。