解决指令输入繁琐：Discord Slash Commands自动补全

Discord斜杠命令（Slash Commands）自推出以来，已经成为机器人交互的主流方式，但很多开发者只使用了基本的固定选项，却忽略了自动补全（Autocomplete）这一强大特性。当你的命令参数需要用户输入一个动态的值，比如服务器内的某个角色名、某个用户的标签，或者城市名，让用户完整手动输入是非常低效且容易出错的。自动补全允许机器人在用户键入时实时返回匹配的建议列表，用户只需点选，无需拼写完整内容。本文将手把手教你如何为你的Discord机器人添加参数自动补全功能，并分享一些实际项目中的注意事项。

认识autocomplete选项与命令定义

在Discord的交互体系中，斜杠命令的选项分为多种类型，包括字符串、整数、布尔值、用户、频道、角色等。并非所有类型都支持自动补全，目前只有字符串、整数、数字这三种标量类型可以启用autocomplete。你需要在注册命令时，给对应选项设置autocomplete: true。以discord.js为例，使用SlashCommandBuilder时，可以这样写：

const { SlashCommandBuilder, ApplicationCommandOptionType } = require('discord.js');

const command = new SlashCommandBuilder()
    .setName('weather')
    .setDescription('查询城市天气')
    .addStringOption(option =>
        option
            .setName('city')
            .setDescription('城市名称')
            .setAutocomplete(true) // 关键：启用自动补全
            .setRequired(true)
    );

这样定义后，当用户输入/weather并开始填写city参数时，Discord客户端会向你的机器人发送一个类型为APPLICATION_COMMAND_AUTOCOMPLETE的interaction，而不是直接执行命令。你的机器人需要在规定时间内返回建议列表。注意，autocomplete选项不会出现在命令的最终执行结果参数中作为一个固定值，它仅仅用于帮助用户输入，所以命令执行时仍然需要接收用户最终选中的值（这个值会被当作字符串传递）。

需要强调的是，autocomplete只应用于用户输入过程中，一旦用户选择了建议或者手动完成输入并提交命令，命令正常执行时不会再触发autocomplete。因此，你的命令逻辑中不需要为autocomplete做特殊处理，只需要将city选项当作普通字符串读取即可。但为了让自动补全真正生效，你必须单独监听并响应autocomplete互动。

响应autocomplete互动并返回建议

当用户正在输入带有autocomplete选项的参数时，Discord会向你的机器人发送一个interactionCreate事件，这个事件的isAutocomplete()方法返回true。你必须尽快调用interaction.respond()方法，传入最多25个应用命令选项选择（choices）。每个选择包含一个name（显示给用户）和一个value（提交给命令的值）。官方要求你必须在3秒内做出响应，否则互动会超时，用户界面会显示错误。

下面是一个基本的监听代码，根据用户已输入的部分字符串返回匹配的城市名称：

client.on('interactionCreate', async interaction => {
    if (!interaction.isAutocomplete()) return;
    if (interaction.commandName !== 'weather') return;

    const focusedOption = interaction.options.getFocused(true);
    if (focusedOption.name !== 'city') return;

    const typed = focusedOption.value.toLowerCase();
    const allCities = ['北京', '上海', '广州', '深圳', '杭州', '南京', '成都', '重庆', '西安', '武汉'];
    const filtered = allCities.filter(city => city.toLowerCase().includes(typed));
    const choices = filtered.slice(0, 25).map(city => ({
        name: city,
        value: city
    }));

    await interaction.respond(choices);
});

这段代码中，interaction.options.getFocused(true)返回当前用户正在聚焦的选项，name是选项名，value是用户已经输入的内容。我们根据这个value进行过滤，返回最多25个匹配项。如果过滤器结果为空，可以返回一个提示选项，例如{ name: '没有匹配的城市', value: 'no_match' }，但注意value也会作为最终值提交，所以如果用户选了提示项，后续命令逻辑需要处理no_match这个特殊值。或者你可以直接返回空数组，Discord客户端会显示“无选项”，但这样体验稍差。

另外，interaction.respond()只能调用一次，且必须在3秒内完成。如果你的数据源是数据库或者远程API，务必做好超时控制。一种常见做法是提前将常用数据加载到内存缓存中，减少响应时间。对于大型数据集，只能返回25个建议，你需要优化排序，把最可能的选择放在前面。

动态数据加载与缓存优化

真实场景中，自动补全的数据往往来自数据库、文件或者第三方API。例如一个服务器管理机器人，用户输入角色名来分配角色，这个角色列表可能在运行时发生变化。每次autocomplete请求都查询数据库是不现实的，不仅仅因为3秒超时的压力，也浪费数据库资源。合理的做法是在机器人启动时加载一次数据，并定时刷新或通过命令手动刷新。你可以使用一个简单的内存缓存对象，存储键值对。

let roleCache = [];
let lastFetchTime = 0;
const CACHE_TTL = 5 * 60 * 1000; // 5分钟

async function getRolesFromCache(guildId) {
    if (Date.now() - lastFetchTime > CACHE_TTL) {
        const guild = await client.guilds.fetch(guildId);
        roleCache = guild.roles.cache
            .filter(role => !role.managed && role.name !== '@everyone')
            .map(role => ({ name: role.name, value: role.id }));
        lastFetchTime = Date.now();
    }
    return roleCache;
}

在autocomplete处理中调用这个函数，再根据用户输入过滤。注意value可以设置为角色ID而不是名称，这样在命令执行时可以准确拿到角色，避免同名角色混淆。不过autocomplete的choice value长度有限制，字符串类型最大100字符，角色ID通常只有18位，完全够用。另外name也可以附带一些额外信息，比如name: '管理员 (@admin)'，帮助用户区分同名角色。

一个容易被忽视的问题是，当用户清空输入框时，你应该返回什么？通常返回默认的热门选项或者全部选项的前25个。你可以在focusedOption.value为空字符串时，返回缓存中的前25个角色。如果数据量超过25个，你需要设计一个合理的排序，比如按角色人数、按字母顺序或者按最近使用。此外，autocomplete互动也受Discord的速率限制影响，虽然单个用户触发频率不高，但大量用户同时使用时会增加你的机器人负载，缓存就显得更加重要。

最后记住，自动补全只是辅助输入，不能完全替代验证。即使用户通过自动补全选择了角色，命令执行时你仍然要检查该角色是否存在、机器人是否有权限操作等。自动补全的价值在于减少用户的记忆负担和打字错误，让你的机器人交互更加流畅自然。

Slash Commands自动补全Discord机器人修改时间：2026-09-21 11:51:29