命令参数

命令参数与命令函数非常相似，它们也需要一个 #[description] 属性，当用户填写命令参数时，这个属性会在 Discord 中显示。

如示例所示，一个 #[rename] 属性也可以使用，这将更改在 Discord 中看到的参数名称。如果不使用该属性，参数将具有与函数相同的名称。

参数还可以用 #[skip] 属性标记。标记为 #[skip] 的参数不允许使用 #[description] 或 #[rename] 属性，并在使用命令时不会被 Discord 显示，但它们将被框架解析。这对于从交互中提取与命令输入无关的数据非常有用。让我们来看一个例子

pub struct ExtractSomething {
    //...
}

#[async_trait]
impl Parse<T> for ExtractSomething
where T: Send + Sync
{
    async fn parse(
        http_client: &WrappedClient,
        data: &T,
        value: Option<&CommandOptionValue>, // <- will be empty since the option was not sent
        resolved: Option<&mut CommandInteractionDataResolved>
    ) -> Result<Self, ParseError>
    {
        // implement parsing logic
    }

    fn kind() -> CommandOptionType {
        // Since the struct will be marked as #[skip] this method won't be used.
        unreachable!()
    }
}

#[command]
#[description = "Something here"]
async fn my_command(
    ctx: &SlashContext</* Data type */>,
    #[skip] my_extractor: ExtractSomething // This won't be seen on discord, but will be parsed
) -> DefaultCommandResult
{
    // Command logic here
    Ok(())
}

重要：所有命令函数都必须将 &SlashContext<T> 作为第一个参数

将选择设置为命令参数

选择是slash命令的一个非常有用的特性，允许开发者为用户提供一些必须选择的选择。

Zephyrus 允许以简单的方式这样做，为此，框架提供了一个派生宏。这个宏的命名方式与 Parse 特性相同，并且只能用于枚举中来定义选项。也可以通过使用 #[parse(rename)] 属性来重命名，并允许更改在 Discord 中看到的选项名称。

#[derive(Parse)]
enum Choices {
    First,
    Second,
    Third,
    #[parse(rename = "Forth")]
    Other
}

#[command]
#[description = "Some description"]
async fn choices(
    ctx: &SlashContext<()>,
    #[description = "Some description"] choice: Choices
) -> DefaultCommandResult
{
    // Command body
    Ok(())
}

自动完成命令

使用 Zephyrus 可以轻松实现自动完成用户输入，只需使用框架提供的 autocomplete 宏。

在这里，让我们看看这个例子。我们将基于这样一个空的命令进行操作

#[command]
#[description = "Some description"]
async fn some_command(
    ctx: &SlashCommand</* Some type */>,
    #[autocomplete = "autocomplete_arg"] #[description = "Some description"] arg: String
) -> DefaultCommandResult
{
    // Logic goes here
    Ok(())
}

如您所注意到的，我们在参数 arg 上添加了一个 autocomplete 属性。指定在其上的输入必须指向一个带有以下属性标记的函数

#[autocomplete]
async fn autocomplete_arg(ctx: AutocompleteContext</* Some type */>) -> Option<InteractionResponseData> {
    // Function body
}

自动完成函数必须有一个 AutocompleteContext<T> 作为唯一的参数，它允许您访问框架存储的数据，同时允许您访问原始交互、框架的 HTTP 客户端和用户输入（如果存在）。

权限

要指定运行命令所需权限，只需在声明命令时使用 #[required_permissions] 属性，或者在声明命令组时使用 .required_permissions 方法。

该属性接受逗号分隔的列表作为输入，例如 Twilight 的权限。让我们看看创建一个需要 MANAGE_CHANNELS 和 MANAGE_MESSAGES 权限的命令会是什么样子。

#[command]
#[description = "Super cool command"]
#[required_permissions(MANAGE_CHANNELS, MANAGE_MESSAGES)]
async fn super_cool_command(ctx: &SlashContext</* Your type */>) -> DefaultCommandResult {
    // Body
    Ok(())
}

命令组

Zephyrus 默认支持 SubCommands 和 SubCommandGroups。

为了举例，假设我们创建了以下命令

#[command]
#[description = "Something"]
async fn something(ctx: &SlashContext</* Your type */>) -> DefaultCommandResult {
    // Command block
    Ok(())
}

有了这个，我们现在可以创建子命令和子命令组

创建子命令

要创建子命令，您需要创建一个组，然后可以添加所有子命令。

#[tokio::main]
async fn main() {
    let framework = Framework::builder()
        .group(|g| {
            g.name("<GROUP_NAME>")
                .description("<GROUP_DESCRIPTION>")
                .add_command(something)
                .add_command(..)
                ..
        })
        .build();
}

创建子命令组

子命令组与子命令非常相似，它们的创建方式几乎相同，但是在注册组之前，我们必须使用 .group 而不是直接使用 .add_command。

#[tokio::main]
async fn main() {
    let framework = Framework::builder()
        .group(|g| {
            g.name("<GROUP_NAME>")
                .description("<GROUP_DESCRIPTION>")
                .group(|sub| { // With this we have created a subcommand group.
                    sub.name("<SUBGROUP_NAME>")
                        .description("<SUBGROUP_DESCRIPTION>")
                        .add_command(something)
                        .add_command(..)
                        ..
                })
        })
        .build();
}

钩子

有三种可用的钩子，分别是 before、after 和 error_handler。

Before

before 钩子在命令之前触发，必须返回一个 bool，指示是否应执行命令。

#[before]
async fn before_hook(ctx: &SlashContext</*Your type*/>, command_name: &str) -> bool {
    // Do something
    
    true // <- if we return true, the command will be executed normally.
}

After

after 钩子在命令执行后触发，并提供命令的结果。

#[after]
async fn after_hook(ctx: &SlashContext</* Your type */>, command_name: &str, result: Option<DefaultCommandResult>) {
    // Do something with the result.
}

特定错误处理

命令可以具有特定的错误处理器。当错误处理器被设置为命令时，如果命令（或其检查中的任何一个）失败，错误处理器将被调用，并且 after 钩子将接收 None 作为第三个参数。然而，如果命令执行完成后没有引发错误，则 after 钩子将接收命令的结果。

让我们看看一个简单的实现

#[error_handler]
async fn handle_ban_error(_ctx: &SlashContext</* Some type */>, error: DefaultError) {
    println!("The ban command had an error");
    
    // Handle the error
}


#[command]
#[description = "Tries to ban the bot itself, raising an error"]
#[error_handler(handle_ban_error)]
async fn ban_itself(ctx: &SlashContext</* Some type */>) -> DefaultCommandResult {
    // A bot cannot ban itself, so this will result in an error.
    ctx.http_client().ban(ctx.interaction.guild_id.unwrap(), Id::new(ctx.application_id.get()))
        .await?;
    
    Ok(())
}

由于命令总是会失败，因为机器人不能禁用自己，所以错误处理器将在每次命令执行时被调用，因此如果设置了，将向 after 钩子传递 None。

检查

检查与 Before 钩子非常相似，但与它不同，它们不是全局的。相反，它们需要分配给每个命令。

让我们看看如何使用它

让我们创建一些检查，如下所示

#[check]
async fn only_guilds(ctx: &SlashContext</* Some type */>) -> Result<bool, DefaultError> {
    // Only execute the command if we are inside a guild.
    Ok(ctx.interaction.guild_id.is_some())
}

#[check]
async fn other_check(_ctx: &SlashContext</* Some type */>) -> Result<bool, DefaultError> {
    // Some other check here.
    Ok(true)
}

然后我们可以使用 check 属性将它们分配给我们的命令，该属性接受逗号分隔的检查列表

#[command]
#[description = "Some description"]
#[checks(only_guilds, other_check)]
async fn my_command(ctx: &SlashContext</* Some type */>) -> DefaultCommandResult {
    // Do something
    Ok(())
}

使用自定义返回类型

框架允许用户指定从命令/检查执行中返回的类型。框架定义如下

pub struct Framework<D, T = (), E = DefaultError>

其中，D 是框架所持数据的类型，而 T 和 E 是命令的返回类型，形式为 Result<T, E>，然而，指定自定义类型是可选的，框架为那些不想自定义错误的人提供了 DefaultCommandResult 和 DefaultError。

根据框架中指定的泛型，after、error_handler 和 check 钩子的参数类型相应变化，因此它们的签名可以解释如下：

钩子后

async fn(&SlashContext</* Some type */>, &str, Option<Result<T, E>>)

错误处理器钩子

async fn(&SlashContext</* Some type */>, E)

命令检查

async fn(&SlashContext</* Some type */>) -> Result<bool, E>

请注意，这些不是真实的签名，因为这些函数返回 Box 包裹的未来。

模态框

从版本 0.8.0 开始，框架提供了一个 derive 宏，使模态框变得尽可能简单。让我们看一个例子

use zephyrus::prelude::*;

#[derive(Modal, Debug)]
#[modal(title = "Test modal")]
struct MyModal {
    field: String,
    #[modal(paragraph, label = "Paragraph")]
    paragraph: String,
    #[modal(placeholder = "This is an optional field")]
    optional: Option<String>
}

#[command]
#[description = "My command description"]
async fn my_command(ctx: &SlashContext</* Some type */>) -> DefaultCommandResult {
    let modal_waiter = ctx.create_modal::<MyModal>().await?;
    let output = modal_waiter.await?;
    
    println!("{output:?}");
    
    Ok(())
}

在这里，'Modal' derive 宏导出模态特质，允许我们创建它们，然后我们可以使用 #[modal(..)} 属性来修改它们如何显示给用户。要查看允许的属性列表，请参阅 宏声明。

目前，只允许 String 和 Option<String> 字段。

批量命令覆盖

如果您想使用 Discord 的 批量覆盖全局应用程序命令 端点，可能还会与一个 命令锁文件 结合使用，那么您将想使用 Framework#twilight_commands。

注意 这需要 bulk 功能。

fn create_framework(
    http_client: Arc<Client>,
    app_id: Id<ApplicationMarker>
) -> Framework<()> {
    Framework::builder(http_client, app_id, ())
        .command(hello)
        .build()
}

fn create_lockfile(framework: Framework<()>) -> Result<()> {
    let commands = framework.twilight_commands();
    let content = serde_json::to_string_pretty(&commands)?;

    let path = concat!(env!("CARGO_MANIFEST_DIR"), "/commands.lock.json").to_string();
	std::fs::write(path, content).unwrap();

    Ok(())
}