開發 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 使用： * 單檔案 ```python= @bot.event async def on_ready(): ... ``` * Cog 方式 ```python= @commands.Cog.listener() async def on_ready(self): ... ``` ## 四、Event 參考： ### Guilds 伺服器 * **加入伺服器** > 當機器人加入伺服器時觸發這個事件。 應用：建立加入伺服器的設定資料、紀錄加入的伺服器 ```python async def on_guild_join(guild: discord.Guild) ``` * **離開伺服器** > 當機器人離開伺服器時觸發這個事件。 應用：移除離開伺服器的設定資料、紀錄離開的伺服器 ```python async def on_guild_remove(guild: discord.Guild) ``` * **更新伺服器** > 當更新伺服器時觸發這個事件。 應用：更新更新伺服器的設定資料 ```python async def on_guild_update(before: discord.Guild, after: discord.Guild) ``` ### Members 成員 * **成員加入** > 當成員加入伺服器時觸發這個事件。 應用：發送歡迎成員訊息、建立成員的設定資料 ```python async def on_member_join(member: discord.Member) ``` * **成員離開** > 當成員離開伺服器時觸發這個事件。 應用：發送離開成員訊息、刪除成員的設定資料 ```python async def on_member_remove(member: discord.Member) ``` * **成員封禁** > 當成員被伺服器封禁時觸發這個事件。 應用：發送封禁成員訊息、新增封禁成員名單 ```python async def on_member_ban(guild: discord.Guild, user: discord.User) ``` * **成員解禁** > 當成員被伺服器解禁時觸發這個事件。 應用：發送解禁成員訊息、移除封禁成員名單 ```python async def on_member_unban(guild: discord.Guild, user: discord.User) ``` ### Messages 訊息 * **發送訊息** > 當用戶在伺服器中發送新訊息時觸發這個事件。 應用：自動回覆訊息、成員經驗值系統 ```python async def on_message(message: discord.Message) ``` * **更改訊息** > 當用戶在伺服器中編輯訊息時觸發這個事件。 應用：紀錄編輯的訊息 ```python async def on_message_edit(before: discord.Message, after: discord.Message) ``` * **刪除訊息** > 當用戶在伺服器中刪除訊息時觸發這個事件。 應用：紀錄刪除的訊息 ```python async def on_message_delete(message: discord.Message) ``` ### Reactions 反應 * **添加反應** > 當用戶在訊息中添加反應時觸發這個事件。 應用：紀錄添加的反應 ```python async def on_reaction_add(reaction: discord.Reaction, user: Union[discord.Member, discord.User]) ``` * **移除反應** > 當用戶在訊息中移除反應時觸發這個事件。 應用：紀錄移除的反應 ```python async def on_reaction_remove(reaction: discord.Reaction, user: Union[discord.Member, discord.User]) ``` * **清空反應** > 當訊息被清空反應時觸發這個事件。 應用：紀錄清空反應的訊息和反應 ```python async def on_reaction_clear(message: discord.Message, reaction: List[discord.Reaction]) ``` ### Interactions 交互 * **監聽交互動作** > 與機器人交互時觸發這個事件，包含斜線指令、按鈕、選單等等。 應用：投票功能、自動身分組功能 ```python async def on_interaction(interaction: discord.Interaction) ``` ### Voice 語音 * **監聽語音動作** > 成員與語音頻道交互時觸發這個事件，包含進入、離開、靜音、拒聽等等。 應用：進出語音頻道成員名單、成員經驗值系統 ```python 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.*