這是一篇使用 discord.py 模組開發的 Discord Bot 進階教學文章。
之前基礎教學中提到，運作 Discord Bot 指令除了使用關鍵字和前綴指令，還有斜線指令、按鈕、選單等等更多方式，未來筆者將會一一介紹。跟著此篇教學步驟能夠學到撰寫斜線指令以及參數如何使用。

歡迎加入筆者的 Discord 伺服器 點此加入

Python Discord Bot 教學文章和程式碼範例 點此前往

一、斜線指令簡介：

Discord 官方在 2021 年 3 月份左右推出斜線指令（Slash Commands），它是 Discord 訊息交互的一種新方式，可以更簡單、直觀的使用指令功能，不僅打出 / 就可以了解 Bot 擁有的指令和各個指令的用途，還能清楚知道指令該傳入哪些參數，讓使用指令更加方便。
00

二、斜線指令基本語法：

🔔 撰寫準備
需要先在 bot.py 中的 async def on_ready() 中添加 await bot.tree.sync()，這行程式碼的功能要讓 Bot 的斜線指令可以同步到 Discord 上，底下程式碼可以順便得知同步多少個指令。

1
2
3
4
5
@bot.event
async def on_ready():
    slash = await bot.tree.sync()
    print(f"目前登入身份 --> {bot.user}")
    print(f"載入 {len(slash)} 個斜線指令")

撰寫斜線指令有單檔案和 Cog 架構兩種方式，簡單列出兩種方式的斜線指令基本架構，而接下來的教學都將使用 Cog 架構，如果不會 Cog 架構可以參考筆者這篇 Python Discord Bot 進階教學 — Cog 篇。

  • 單檔案

    🔔 裝飾器從 @bot.command() 改成 @bot.tree.command()，參數 ctx 更改成 interaction

    1
    2
    3
    4
    5
    6
    # name指令顯示名稱，description指令顯示敘述
    # name的名稱，中、英文皆可，但不能使用大寫英文
    @bot.tree.command(name = "hello", description = "Hello, world!")
    async def hello(interaction: discord.Interaction):
        # 回覆使用者的訊息
        await interaction.response.send_message("Hello, world!")
  • Cog 架構

    🔔 需要在程式開頭導入 app_command 指令

    1
    from discord import app_commands
    1
    2
    3
    4
    5
    6
    # name指令顯示名稱，description指令顯示敘述
    # name的名稱，中、英文皆可，但不能使用大寫英文
    @app_commands.command(name = "hello", description = "Hello, world!")
    async def hello(self, interaction: discord.Interaction):
        # 回覆使用者的訊息
        await interaction.response.send_message("Hello, world!")
    01 02 03

三、斜線指令額外語法：

更多有關斜線指令的資料可以參考 discord.py API。

參數敘述

@app_commands.describe() 是一個讓參數增加文字敘述的函式，需要注意函式中的變數名稱需要和參數的名字一模一樣，否則會因為無法辨別而發生錯誤。

1
2
3
4
5
6
# @app_commands.describe(參數名稱 = 參數敘述)
# 參數: 資料型態，可以限制使用者輸入的內容
@app_commands.command(name = "add", description = "計算相加值")
@app_commands.describe(a = "輸入數字", b = "輸入數字")
async def add(self, interaction: discord.Interaction, a: int, b: int):
    await interaction.response.send_message(f"Total: {a + b}")

04 05

可選參數

🔔 需要在程式開頭導入 typing 模組中的 Optional 工具。

1
from typing import Optional

typing 模組中的 Optional 工具可以讓參數變成可選，可讓使用者依據自身需求填寫。

1
2
3
4
5
6
7
# 參數: Optional[資料型態]，參數變成可選，可以限制使用者輸入的內容
@app_commands.command(name = "say", description = "大聲說出來")
@app_commands.describe(name = "輸入人名", text = "輸入要說的話")
async def say(self, interaction: discord.Interaction, name: str, text: Optional[str] = None):
    if text == None:
        text = "。。。"
    await interaction.response.send_message(f"{name} 說 「{text}」")

06 07

選項清單

🔔 為了撰寫程式碼更方便、快速，可以先將 discord.app_commands 中的 Choice 工具導入。

1
from discord.app_commands import Choice

@app_commands.choices() 是一個製作讓使用者選擇的選項清單的函式，要注意每個參數最多只能添加 25 個選項。
更多選項清單的寫法，可以參考此篇的 discord.py API。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# @app_commands.choices(參數 = [Choice(name = 顯示名稱, value = 隨意)])
@app_commands.command(name = "order", description = "點餐機")
@app_commands.describe(meal = "選擇餐點", size = "選擇份量")
@app_commands.choices(
    meal = [
        Choice(name = "漢堡", value = "hamburger"),
        Choice(name = "薯條", value = "fries"),
        Choice(name = "雞塊", value = "chicken_nuggets"),
    ],
    size = [
        Choice(name = "大", value = 0),
        Choice(name = "中", value = 1),
        Choice(name = "小", value = 2),
    ]
)
async def order(self, interaction: discord.Interaction, meal: Choice[str], size: Choice[int]):
    # 獲取使用指令的使用者名稱
    customer = interaction.user.name
    # 使用者選擇的選項資料，可以使用name或value取值
    meal = meal.value
    size = size.value
    await interaction.response.send_message(f"{customer} 點了 {size} 號 {meal} 餐")

08 09

此次教學已經結束，感謝各位看完整篇文章，如果文章中有哪些不懂、不清楚，或者覺得需要修正、更改，歡迎跟筆者反映，一起讓文章內容更完整，幫助每個人都能輕鬆學會撰寫斜線指令。
當初筆者要從前綴指令轉成斜線指令的寫法時，遇到許多的問題。比如照著官方文檔的程式碼範例撰寫，執行 Discord Bot 時卻沒有顯示出任何斜線指令，經過上網查詢和詢問他人得知，必須要加 await bot.tree.sync() 到程式碼中，才能讓斜線指令同步到 Discord 上。有時遇到困擾自己很久的問題，真的需要別人拋磚引玉才知道該如何解決。