開發 Discord Bot 時，除了撰寫讓使用者使用的指令和交互功能之外，應用 Discord 中的各種事件（Event）也是至關重要的一部份，以下整理開發 Discord Bot 時常用到的事件。

:::success
:book: **更多 Python Discord Bot 教學系列和程式範例**
https://github.com/smallshawn95/Python-Discord-Bot-Course
:::

---

[TOC]

---

## 一、Event 簡介：
事件（Event）是指某些特定的時刻或情境下，系統或應用程序會自動觸發的通知或反應。在 Discord Bot 開發中，事件是指某些特定動作在 Discord 伺服器中發生時，Discord API 會向 Bot 發送通知，開發者可以根據這些事件來執行相對應的操作。
舉例來說，Discord Bot 中的 `on_ready()` 函式就是一個事件，當 Discord Bot 完成準備階段時會觸發這個事件。更多其他的事件能夠實作出不同功能，例如：表情符號發送身分組、根據訊息和通話計算經驗值等等。
想了解更多 Discord 的事件資訊，可以參考 [Discord.py API](https://discordpy.readthedocs.io/en/stable/api.html#event-reference)。

## 二、Event 差異：
如果將事件細分，有分低階事件以及高階事件兩種，以下簡單介紹。

* **低階事件**
低階事件是 Discord API 直接觸發的原始事件，它們提供了更細度的控制和更多的數據。使用低階事件時，你處理的是原始 JSON 數據，需要手動解析並處理事件。這些事件命名通常使用 `on_raw_*` 開頭，例如：`on_raw_message_edit`、`on_raw_reaction_add`。
* **高階事件**
高階事件是 Discord.py 對低階事件進行封裝，將事件與 Discord.py 的模型結合，提供了更方便的 API。使用高階事件時，你可以直接訪問 Discord.py 中的模型對象，而不需要處理原始數據。這些事件命名通常使用 `on_*` 開頭，例如：`on_message_edit`、`on_reaction_add`。

簡而言之，高階事件更容易使用，適合初學者；低階事件提供更多控制權，適合有特定需求的開發者。接下來的參考大部分提供高階事件的方式。

## 三、Event 使用：
* 單檔案

@bot.event
async def on_ready():
    ...

* Cog 方式

@commands.Cog.listener()
async def on_ready(self):
    ...

## 四、Event 參考：
### Guilds 伺服器
* **加入伺服器**
> 當機器人加入伺服器時觸發這個事件。

應用：建立加入伺服器的設定資料、紀錄加入的伺服器

    async def on_guild_join(guild: discord.Guild)

* **離開伺服器**
> 當機器人離開伺服器時觸發這個事件。

應用：移除離開伺服器的設定資料、紀錄離開的伺服器

    async def on_guild_remove(guild: discord.Guild)

* **更新伺服器**
> 當更新伺服器時觸發這個事件。

應用：更新更新伺服器的設定資料

    async def on_guild_update(before: discord.Guild, after: discord.Guild)

### Members 成員
* **成員加入**
> 當成員加入伺服器時觸發這個事件。

應用：發送歡迎成員訊息、建立成員的設定資料

    async def on_member_join(member: discord.Member)

* **成員離開**
> 當成員離開伺服器時觸發這個事件。

應用：發送離開成員訊息、刪除成員的設定資料

    async def on_member_remove(member: discord.Member)

* **成員封禁**
> 當成員被伺服器封禁時觸發這個事件。

應用：發送封禁成員訊息、新增封禁成員名單

    async def on_member_ban(guild: discord.Guild, user: discord.User)

* **成員解禁**
> 當成員被伺服器解禁時觸發這個事件。

應用：發送解禁成員訊息、移除封禁成員名單

    async def on_member_unban(guild: discord.Guild, user: discord.User)

### Messages 訊息
* **發送訊息**
> 當用戶在伺服器中發送新訊息時觸發這個事件。

應用：自動回覆訊息、成員經驗值系統

    async def on_message(message: discord.Message) 

* **更改訊息**
> 當用戶在伺服器中編輯訊息時觸發這個事件。

應用：紀錄編輯的訊息

    async def on_message_edit(before: discord.Message, after: discord.Message)

* **刪除訊息**
> 當用戶在伺服器中刪除訊息時觸發這個事件。

應用：紀錄刪除的訊息

    async def on_message_delete(message: discord.Message)

### Reactions 反應
* **添加反應**
> 當用戶在訊息中添加反應時觸發這個事件。

應用：紀錄添加的反應

    async def on_reaction_add(reaction: discord.Reaction, user: Union[discord.Member, discord.User])

* **移除反應**
> 當用戶在訊息中移除反應時觸發這個事件。

應用：紀錄移除的反應

    async def on_reaction_remove(reaction: discord.Reaction, user: Union[discord.Member, discord.User])

* **清空反應**
> 當訊息被清空反應時觸發這個事件。

應用：紀錄清空反應的訊息和反應

    async def on_reaction_clear(message: discord.Message, reaction: List[discord.Reaction])

### Interactions 交互
* **監聽交互動作**
> 與機器人交互時觸發這個事件，包含斜線指令、按鈕、選單等等。

應用：投票功能、自動身分組功能

    async def on_interaction(interaction: discord.Interaction)

### Voice 語音
* **監聽語音動作**
> 成員與語音頻道交互時觸發這個事件，包含進入、離開、靜音、拒聽等等。

應用：進出語音頻道成員名單、成員經驗值系統

    async def on_voice_state_update(member: discord.Member, before: discord.VoiceState, after: discord.VoiceState)

---
:::info
📢 **歡迎加入我的 Discord 伺服器**
https://discord.gg/Jtd3eVrFJs
:::
*Copyright © 2024 SmallShawn95. All rights reserved.*