這是一篇使用 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 上。有時遇到困擾自己很久的問題,真的需要別人拋磚引玉才知道該如何解決。