Discord.py 斜杠命令开发指南：正确处理 Interaction 对象

在 `discord.py` 中开发斜杠命令时，理解 `commands.Context` 与 `discord.interactions.Interaction` 对象的区别至关重要。本文将详细阐述这两种对象在不同命令类型中的作用，并指导开发者如何为斜杠命令正确使用 `Interaction` 对象及其响应机制，避免常见的类型错误，确保命令功能正常运行。

一、理解 discord.py 中的命令上下文

discord.py 提供了两种主要的命令类型：传统前缀命令和现代应用命令（斜杠命令）。这两种命令在处理用户输入时，会向其回调函数传递不同类型的上下文对象。

1. 传统前缀命令与 commands.Context

对于使用 commands.Bot.command 装饰器定义的前缀命令（例如，以 ! 或 / 开头的文本命令），其回调函数接收的第一个参数是一个 commands.Context 对象。这个对象包含了命令触发的完整上下文信息，包括消息对象、发起命令的用户、所在的频道、Guild 等。开发者可以通过 ctx.send()、ctx.reply() 等方法进行响应。

示例：

import discord
from discord.ext import commands

# ... (Bot 初始化) ...

@client.command(name='greet')
async def greet(ctx):
    """一个简单的前缀命令示例"""
    await ctx.send(f'你好，{ctx.author.display_name}！')

2. 应用命令（斜杠命令）与 discord.interactions.Interaction

随着 Discord API 的发展，应用命令（通常是斜杠命令，如 /marry）成为主流。这类命令通过 client.tree.command 装饰器定义，并且它们不通过传统的文本消息解析器触发。当用户在 Discord 客户端中执行一个斜杠命令时，Discord API 会向机器人发送一个“交互”（Interaction）事件。因此，斜杠命令的回调函数接收的第一个参数是一个 discord.interactions.Interaction 对象。

Interaction 对象代表了用户与应用程序之间的具体交互，它提供了与该交互相关的特定信息和响应机制。试图将 Interaction 对象当作 Context 对象来使用（例如调用 ctx.reply()）会导致错误，因为它们的方法和属性是不同的。

二、正确实现斜杠命令

要正确实现斜杠命令，关键在于理解其回调函数应接收 discord.Interaction 对象，并使用该对象提供的特定方法来处理响应。

1. 修正命令签名

将斜杠命令的第一个参数从 ctx 更改为 interaction（或任何其他名称，但类型应为 discord.Interaction），并使用类型提示以增强代码可读性和健壮性。

LobeHub

LobeChat brings you the best user experience of ChatGPT, OLLaMA, Gemini, Claude

201

查看详情

错误示例（原始问题）：

@client.tree.command(name='marry', description="Suggest to marry")
async def marry(ctx, user: discord.Member): # 错误：这里应该是 interaction
    ctx.reply(f'{ctx.author} make a proposal to marry {user}') # 错误：Interaction 对象没有 reply 方法

正确实现示例：

import discord
from discord.ext import commands
from discord import app_commands # 确保导入 app_commands 模块

# ... (Bot 初始化代码) ...

@client.tree.command(name='marry', description="Suggest to marry")
async def marry(interaction: discord.Interaction, user: discord.Member):
    """
    一个斜杠命令示例，演示如何正确处理 Interaction 对象。
    interaction: discord.Interaction - 代表用户与应用程序的交互。
    user: discord.Member - 命令的第二个参数，代表被提及的用户。
    """
    # interaction.user 代表发起交互的用户
    # interaction.response 用于发送初始响应
    await interaction.response.send_message(f'{interaction.user.display_name} 向 {user.display_name} 提出了结婚请求！')

    # 注意：interaction.response.send_message 只能调用一次作为初始响应。
    # 如果需要发送后续消息，应使用 interaction.followup.send。
    # await interaction.followup.send("这是一个后续消息。")

2. Interaction 对象的响应机制

discord.Interaction 对象提供了专门用于响应交互的方法，它们与 Context 对象的方法有所不同：

• interaction.response.send_message(content, ...): 这是发送斜杠命令的首次响应的推荐方法。它会立即向用户显示消息。每个交互只能调用一次 send_message 或其他 interaction.response 方法。
• interaction.response.defer(ephemeral=False): 如果命令需要较长时间处理，可以先调用此方法发送一个“正在思考”的临时响应，以避免命令超时。之后再通过 interaction.followup.send() 发送实际消息。
• interaction.followup.send(content, ...): 在首次响应（无论是 send_message 还是 defer）之后，如果需要发送额外的消息，应使用 interaction.followup.send()。这允许在同一个交互中发送多条消息。

三、注意事项与最佳实践

1. 命令同步

斜杠命令需要在机器人启动后同步到 Discord。这通常在 on_ready 事件中完成，确保所有定义的斜杠命令都能被 Discord 识别和使用。

import asyncio
import discord
from discord.ext import commands
from discord import app_commands
import configure # 假设 configure 模块包含 BOT_TOKEN 和 BOT_NAME

intents = discord.Intents.all()
BOT_TOKEN = configure.config["token"]
BOT_NAME = configure.config["name"]

client = commands.Bot(intents=intents, command_prefix="/")

@client.event
async def on_ready():
    print("机器人已成功上线！")
    try:
        # 同步所有注册的斜杠命令
        synced = await client.tree.sync()
        print(f"已同步 {len(synced)} 个斜杠命令到 Discord。")
    except Exception as e:
        print(f"同步斜杠命令失败: {e}")

# ... (其他命令定义) ...

async def main():
    await client.start(BOT_TOKEN)

if __name__ == "__main__":
    asyncio.run(main())

2. contextlib = True 错误解析

在问题中，开发者尝试在 @client.tree.command 装饰器中使用 contextlib = True 参数。这是一个常见的误解，因为 contextlib 是用于传统前缀命令 commands.command() 装饰器的一个参数，它控制是否将 Context 对象传递给命令。对于斜杠命令，client.tree.command() 装饰器不接受此参数，因为它总是处理 Interaction 对象，因此尝试使用它会导致 TypeError。

3. 避免混淆

始终根据您定义的命令类型（前缀命令或斜杠命令）来预期和使用正确的上下文对象。这是编写健壮且无错误 discord.py 机器人的基础。

总结

在 discord.py 中，理解并正确区分 commands.Context 对象和 discord.interactions.Interaction 对象是开发不同类型命令的关键。前缀命令使用 Context，而斜杠命令则使用 Interaction。为斜杠命令正确地将第一个参数类型定义为 discord.Interaction，并利用其 response 和 followup 属性来处理消息响应，将确保您的机器人能够无缝地与 Discord 的应用命令系统集成，提供流畅的用户体验。同时，不要忘记在机器人启动时同步您的斜杠命令。

以上就是Discord.py 斜杠命令开发指南：正确处理 Interaction 对象的详细内容，更多请关注php中文网其它相关文章！