在 Discord 斜杠命令中实现分层子命令（以 nextcord 为例）

理解 Discord 应用命令中的子命令

在 discord 的应用命令（application commands，即斜杠命令）体系中，命令名称本身不允许直接包含空格。当用户尝试创建如 /channellink list 这样的命令时，实际上并不是在命令名称中加入了空格，而是利用了 discord api 提供的子命令（subcommands）机制。子命令允许开发者将一个主命令（parent command）拆分为多个功能独立的子功能，每个子功能都可以拥有自己独特的参数。这种结构不仅使得命令体系更加清晰，也为复杂的交互提供了可能。

例如，/channellink list 中的 channellink 是主命令，而 list 则是其下的一个子命令。类似地，/channellink initiate 和 /channellink terminate 也是 channellink 的不同子命令。每个子命令都可以有不同的参数，这与简单的选择（choices）参数不同，因为选择参数通常只改变一个固定参数的值，而子命令则代表了完全不同的操作路径。

使用 nextcord 实现子命令

nextcord 库（以及其前身 discord.py）提供了直观的装饰器来构建这种分层命令结构。核心思想是先定义一个主命令，然后将各个子命令定义为该主命令的方法，并使用特定的装饰器将其注册为子命令。

以下是一个具体的实现示例，展示了如何为 /channellink 命令添加 initiate、terminate 和 list 三个子命令：

Krikey AI

68

查看详情

from nextcord import Interaction, slash_command
from nextcord.ext.commands import Bot, Cog

class ChannelLinkCommands(Cog):
    def __init__(self, bot: Bot):
        self.bot = bot

    # 定义主命令 channellink
    # 这里的 guild_ids 参数用于指定命令注册到的服务器ID，在开发阶段非常有用
    # 如果省略，则命令将注册为全局命令（可能需要1小时才能同步）
    @slash_command(guild_ids=[123456789012345678]) # 替换为你的服务器ID
    async def channellink(self, interaction: Interaction):
        # 此函数通常不会被直接执行，因为它包含子命令。
        # 如果用户只输入 /channellink 而没有子命令，Discord 客户端会提示选择子命令。
        pass

    # 定义 channellink 的子命令 initiate
    @channellink.subcommand(name="initiate", description="初始化频道链接")
    async def initiate_link(self, interaction: Interaction, source_channel: str, target_channel: str):
        """
        处理 /channellink initiate 命令。
        例如：可以在这里添加逻辑来初始化两个频道之间的消息转发。
        """
        await interaction.response.send_message(
            f"正在初始化从 {source_channel} 到 {target_channel} 的频道链接。", 
            ephemeral=True # 私密回复，只有执行者可见
        )
        # 实际的初始化逻辑...

    # 定义 channellink 的子命令 terminate
    @channellink.subcommand(name="terminate", description="终止频道链接")
    async def terminate_link(self, interaction: Interaction, link_id: int):
        """
        处理 /channellink terminate 命令。
        例如：根据链接ID终止一个已存在的频道链接。
        """
        await interaction.response.send_message(
            f"正在终止 ID 为 {link_id} 的频道链接。", 
            ephemeral=True
        )
        # 实际的终止逻辑...

    # 定义 channellink 的子命令 list
    @channellink.subcommand(name="list", description="列出所有频道链接")
    async def list_links(self, interaction: Interaction):
        """
        处理 /channellink list 命令。
        例如：列出当前服务器中所有已配置的频道链接。
        """
        await interaction.response.send_message(
            "以下是当前所有活跃的频道链接：\n- 链接1\n- 链接2", 
            ephemeral=True
        )
        # 实际的列表查询逻辑...

def setup(bot: Bot):
    """
    将 Cog 添加到机器人。
    """
    bot.add_cog(ChannelLinkCommands(bot))

代码解析：

1. class ChannelLinkCommands(Cog):: 所有的命令都封装在一个 Cog（命令组）中，这是一种推荐的组织方式。
2. @slash_command(guild_ids=[...]):
   • 这是定义主命令 /channellink 的装饰器。
   • guild_ids 参数非常重要，特别是在开发阶段。它允许你将命令注册到特定的服务器，这样命令会立即同步，而不需要等待全局命令可能长达一小时的同步时间。在生产环境中，如果命令是为所有服务器设计的，可以省略此参数，使其成为全局命令。
   • async def channellink(self, interaction: Interaction):：这个主命令函数本身通常不包含任何逻辑。当用户输入 /channellink 时，Discord 客户端会提示用户选择一个子命令。只有当主命令不包含任何子命令时，此函数才会被直接执行。
3. @channellink.subcommand(...):
   • 这是定义子命令的关键。它使用主命令对象（channellink）作为前缀，然后调用 .subcommand 方法。
   • name 参数定义了子命令的名称（例如 initiate、terminate、list），这将是用户在 Discord 客户端中看到的命令部分。
   • description 参数提供了子命令的简短描述，会在 Discord 的命令提示中显示。
   • 每个子命令函数（如 initiate_link, terminate_link, list_links）都可以定义自己的参数（例如 source_channel, target_channel, link_id），这些参数会在用户输入子命令时作为选项出现。

注意事项与最佳实践

• 参数独立性：子命令最强大的地方在于每个子命令都可以有自己独立的参数集，这使得它们能够执行完全不同的操作，而不仅仅是基于一个参数进行区分。
• 主命令的执行：如果一个主命令下定义了子命令，那么该主命令本身的回调函数（例如上述 channellink 函数）通常不会被直接执行。Discord 客户端会引导用户选择一个子命令。
• 子命令组（Subcommand Groups）：除了子命令，Discord 还支持子命令组，允许更深层次的嵌套，例如 /parent_command group subcommand。这可以通过 @parent_command.subcommand_group 装饰器实现，进一步组织复杂的命令结构。
• 错误处理：在实际应用中，每个子命令的逻辑内部都应该包含适当的错误处理，例如验证用户输入、处理API调用失败等。
• 异步操作：Discord 机器人编程是异步的，确保所有的命令回调函数都是 async 函数，并且在执行耗时操作时使用 await。

总结

通过利用 Discord 的子命令机制，开发者可以构建出结构清晰、功能丰富且易于使用的斜杠命令。nextcord 库提供的 @slash_command 和 .subcommand 装饰器极大地简化了这一过程，使得实现如 /channellink list 这样带“空格”效果的分层命令变得简单直观。掌握子命令的运用，是构建专业级 Discord 机器人的关键一步。

以上就是在 Discord 斜杠命令中实现分层子命令（以 nextcord 为例）的详细内容，更多请关注php中文网其它相关文章！