Команды (`commands`)

Обработка команд на стероидах.

Этот плагин предоставляет различные возможности для работы с командами, которых нет в основной библиотеке для обработки команд. Вот краткий обзор возможностей, которые вы получаете с этим плагином:

Улучшенная читаемость кода за счет инкапсуляции middleware с определениями команд
Синхронизация меню команд через setMyCommands
Улучшенная группировка и организация команд
Возможность ограничить область действия команды, например: доступ только администраторам группы или в каналах и т.д.
Создание переводов для команды
Функция Возможно, вы имели в виду ...?, которая находит ближайшую команду при ошибочном вводе пользователем
Нечувствительность к регистру при сравнении команд
Настройка пользовательского поведения для команд, которые явно упоминают вашего бота, например: /start@your_bot
Пользовательские префиксы для команд, например: +, ? или любой другой символ вместо /
Поддержка команд, которые находятся не в начале сообщения
Команды с использованием регулярных выражений!

Все эти возможности реализуются благодаря тому, что вы будете определять одну или несколько центральных структур команд, описывающих команды вашего бота.

Основное использование

Прежде чем углубляться, давайте посмотрим, как зарегистрировать и обработать команду с помощью плагина:

typescript

const myCommands = new CommandGroup();

myCommands.command(
  "hello",
  "Поздороваться",
  (ctx) => ctx.reply(`Привет, мир!`),
);

bot.use(myCommands);

Эта команда регистрирует новую команду /hello для вашего бота, которая будет обрабатываться переданным middleware.

Теперь давайте рассмотрим дополнительные инструменты, которые предоставляет этот плагин.

Импортирование

Прежде всего, вот как вы можете импортировать все необходимые типы и классы, которые предоставляет плагин.

TypeScriptJavaScriptDeno

import {
  CommandGroup,
  commandNotFound,
  commands,
  type CommandsFlavor,
} from "@grammyjs/commands";

const { CommandGroup, commands, commandNotFound } = require(
  "@grammyjs/commands",
);

import {
  CommandGroup,
  commandNotFound,
  commands,
  type CommandsFlavor,
} from "https://deno.land/x/grammy_commands@v1.0.3/mod.ts";

Теперь, когда с импортом разобрались, давайте посмотрим, как сделать наши команды видимыми для пользователей.

Настройка пользовательского меню команд

После того как вы определили свои команды с помощью экземпляра класса CommandGroup, вы можете вызвать метод setCommands, который зарегистрирует все заданные команды для вашего бота.

typescript

const myCommands = new CommandGroup();

myCommands.command("hello", "Поздороваться", (ctx) => ctx.reply("Привет!"));
myCommands.command("start", "Запустить бота", (ctx) => ctx.reply("Запуск..."));

bot.use(myCommands);

await myCommands.setCommands(bot);

Это позволит отображать каждую зарегистрированную вами команду в меню в приватном чате с вашим ботом или когда пользователи набирают / в чате, где присутствует ваш бот.

Контекстные команды

Что, если вы хотите, чтобы некоторые команды отображались только для определённых пользователей? Например, представьте, что у вас есть команды login и logout. Команда login должна отображаться только для незарегистрированных пользователей, и наоборот. Вот как это можно реализовать с помощью плагина команд:

TypeScriptJavaScript

typescript

// Используйте расширитель для создания собственного контекста
type MyContext = Context & CommandsFlavor;

// Используйте новый контекст для создания экземпляра бота
const bot = new Bot<MyContext>("токен");

// Регистрируем контекстную команду
bot.use(commands());

const loggedOutCommands = new CommandGroup();
const loggedInCommands = new CommandGroup();

loggedOutCommands.command(
  "login",
  "Начать сессию с ботом",
  async (ctx) => {
    await ctx.setMyCommands(loggedInCommands);
    await ctx.reply("Добро пожаловать! Сессия начата!");
  },
);

loggedInCommands.command(
  "logout",
  "Завершить сессию с ботом",
  async (ctx) => {
    await ctx.setMyCommands(loggedOutCommands);
    await ctx.reply("До свидания :)");
  },
);

bot.use(loggedInCommands);
bot.use(loggedOutCommands);

// По умолчанию пользователи не авторизованы,
// поэтому можно установить команды для незарегистрированных
await loggedOutCommands.setCommands(bot);

javascript

// Регистрируем контекстную команду
bot.use(commands());

const loggedOutCommands = new CommandGroup();
const loggedInCommands = new CommandGroup();

loggedOutCommands.command(
  "login",
  "Начать сессию с ботом",
  async (ctx) => {
    await ctx.setMyCommands(loggedInCommands);
    await ctx.reply("Добро пожаловать! Сессия начата!");
  },
);

loggedInCommands.command(
  "logout",
  "Завершить сессию с ботом",
  async (ctx) => {
    await ctx.setMyCommands(loggedOutCommands);
    await ctx.reply("До свидания :)");
  },
);

bot.use(loggedInCommands);
bot.use(loggedOutCommands);

// По умолчанию пользователи не авторизованы,
// поэтому можно установить команды для незарегистрированных
await loggedOutCommands.setCommands(bot);

Таким образом, когда пользователь вызывает /login, его список команд изменится и будет содержать только команду logout. Удобно, правда?

Ограничения на имена команд

Как указано в документации API Telegram Bot, имена команд могут состоять только из:

1-32 символов. Разрешены только строчные английские буквы, цифры и подчеркивания.

Таким образом, вызов setCommands или setMyCommands с именем команды, не соответствующим нижнему регистру, вызовет исключение. Команды, не соответствующие этим правилам, всё равно могут быть зарегистрированы, использованы и обработаны, но не будут отображаться в меню пользователя.

Учтите, что setCommands и setMyCommands влияют только на отображаемые команды в меню команд пользователя и не ограничивают доступ к ним. Вы узнаете, как реализовать ограничение доступа к командам в разделе Команды с областью видимости.

Группировка команд

Поскольку мы можем разделять и группировать команды в разные экземпляры, это позволяет намного более удобно организовывать файлы команд.

Допустим, мы хотим создать команды, доступные только для разработчиков. Мы можем реализовать это с помощью следующей структуры кода:

ascii

src/
├─ commands/
│  ├─ admin.ts
│  ├─ users/
│  │  ├─ group.ts
│  │  ├─ say-hi.ts
│  │  ├─ say-bye.ts
│  │  ├─ ...
├─ bot.ts
├─ types.ts
tsconfig.json

Следующий блок кода демонстрирует, как можно реализовать группу команд, доступных только для разработчиков, и обновить меню команд в клиенте Telegram соответствующим образом. Обратите внимание на разные шаблоны, используемые в файлах admin.ts и group.ts.

export type MyContext = Context & CommandsFlavor<MyContext>;

import { devCommands } from "./commands/admin.ts";
import { userCommands } from "./commands/users/group.ts";
import type { MyContext } from "./types.ts";

export const bot = new Bot<MyContext>("токен");

bot.use(commands());

bot.use(userCommands);
bot.use(devCommands);

import { userCommands } from './users/group.ts'
import type { MyContext } from '../types.ts'

export const devCommands = new CommandGroup<MyContext>()

devCommands.command('devlogin', 'Приветствие', async (ctx, next) => {
   if (ctx.from?.id === ctx.env.DEVELOPER_ID) {
      await ctx.reply('Привет мне')
      await ctx.setMyCommands(userCommands, devCommands)
   } else {
     await next()
   }
})

devCommands.command('usercount', 'Приветствие', async (ctx, next) => {
   if (ctx.from?.id === ctx.env.DEVELOPER_ID) {
      await ctx.reply(
        `Активные пользователи: ${/** Ваша логика здесь */}`
    )
   } else {
     await next()
   }
})

devCommands.command('devlogout', 'Приветствие', async (ctx, next) => {
    if (ctx.from?.id === ctx.env.DEVELOPER_ID) {
       await ctx.reply('Пока мне')
       await ctx.setMyCommands(userCommands)
   } else {
     await next()
   }
 })

import sayHi from "./say-hi.ts";
import sayBye from "./say-bye.ts";
import etc from "./another-command.ts";
import type { MyContext } from "../../types.ts";

export const userCommands = new CommandGroup<MyContext>()
  .add([sayHi, sayBye]);

import type { MyContext } from "../../types.ts";

export default new Command<MyContext>("sayhi", "Приветствие", async (ctx) => {
  await ctx.reply("Привет, маленький пользователь!");
});

Вы заметили, что вы можете регистрировать отдельные команды в экземпляр CommandGroup с помощью метода .add или напрямую через метод .command(...)? Это позволяет создавать как структуру из одного файла, как в файле admin.ts, так и более распределенную файловую структуру, как в файле group.ts.

Всегда используйте группы команд

При создании и экспорте команд с использованием конструктора Command, обязательно регистрируйте их в экземпляре CommandGroup с помощью метода .add. Без этого они бесполезны, так что не забудьте сделать это на каком-то этапе.

Плагин также требует, чтобы для заданного CommandGroup и его соответствующих Commands использовался один и тот же тип контекста, что помогает избежать подобных ошибок на раннем этапе!

Сочетание этих знаний с информацией из следующего раздела выведет вашу работу с командами на новый уровень.

Команды с областью видимости

Знаете ли вы, что можно показывать разные команды в разных чатах в зависимости от типа чата, языка и даже статуса пользователя в группе? Это то, что Telegram называет Области видимости команд.

Области видимости команд — это отличная функция, но использовать её вручную может быть очень сложно, поскольку трудно отслеживать все области и команды, которые они предоставляют. Кроме того, при использовании только областей команд вам приходится вручную добавлять фильтрацию внутри каждой команды, чтобы убедиться, что они будут выполняться только для нужных областей видимости. Синхронизировать эти два момента бывает непросто, и именно поэтому существует этот плагин. Посмотрите, как это делается.

Класс Command, возвращаемый методом command, предоставляет метод под названием addToScope. Этот метод принимает в качестве параметров BotCommandScope вместе с одним или несколькими обработчиками и регистрирует эти обработчики для выполнения в указанной области.

Вам даже не нужно беспокоиться о вызове filter, метод addToScope гарантирует, что ваш обработчик будет вызываться только в нужном контексте.

Вот пример команды с определённой областью:

const myCommands = new CommandGroup();

myCommands
  .command("start", "Инициализирует конфигурацию бота")
  .addToScope(
    { type: "all_private_chats" },
    (ctx) => ctx.reply(`Привет, ${ctx.chat.first_name}!`),
  )
  .addToScope(
    { type: "all_group_chats" },
    (ctx) => ctx.reply(`Привет, участники ${ctx.chat.title}!`),
  );

Команду start теперь можно вызывать как из личных, так и из групповых чатов, и ответ будет отличаться в зависимости от того, откуда поступил вызов. Теперь, если вызвать myCommands.setCommands, команда start будет зарегистрирована как в личных, так и в групповых чатах.

Вот пример команды, доступной только администраторам группы.

adminCommands
  .command("secret", "Только для админов")
  .addToScope(
    { type: "all_chat_administrators" },
    (ctx) => ctx.reply("Бесплатный торт!"),
  );

А вот пример команды, доступной только в группах

myCommands
  .command("fun", "Смех")
  .addToScope(
    { type: "all_group_chats" },
    (ctx) => ctx.reply("Хаха"),
  );

Обратите внимание, что при вызове метода command создаётся новая команда. Если вы добавите обработчик, он будет применяться к области этой команды по умолчанию. Вызов addToScope для этой команды добавит новый обработчик, который будет фильтроваться по заданной области видимости. Посмотрите на этот пример.

myCommands
  .command(
    "default",
    "Команда по умолчанию",
    // Эта функция будет вызываться, если вы не находитесь в групповом чате или если пользователь не является администратором
    (ctx) => ctx.reply("Привет из области видимости по умолчанию"),
  )
  .addToScope(
    { type: "all_group_chats" },
    // Эта функция будет вызываться только для не админов в группе
    (ctx) => ctx.reply("Привет, групповой чат!"),
  )
  .addToScope(
    { type: "all_chat_administrators" },
    // Эта функция будет вызываться для администраторов групп, когда они находятся внутри этой группы
    (ctx) => ctx.reply("Привет, админ!"),
  );

Переводы команд

Ещё одной мощной функцией является возможность задавать разные названия для одной и той же команды и соответствующие описания в зависимости от языка пользователя. Плагин команд упрощает это с помощью метода localize. Вот пример:

myCommands
  // Сначала нужно установить название и описание по умолчанию
  .command("hello", "Say hello")
  // А затем можно задать локализованные варианты
  .localize("ru", "privet", "Поздороваться");

Добавьте столько вариантов, сколько хотите! Плагин сам позаботится об их регистрации, когда вы вызовете myCommands.setCommands.

Для удобства grammY экспортирует объект, аналогичный перечислению LanguageCodes, который можно использовать для более идиоматического подхода:

TypeScriptJavaScriptDeno

import { LanguageCodes } from "grammy/types";

myCommands.command(
  "chef",
  "Steak delivery",
  (ctx) => ctx.reply("Steak on the plate!"),
)
  .localize(
    LanguageCodes.Russian,
    "chefpovar",
    "Стейк на тарелке!",
  );

const { LanguageCodes } = require("grammy/types");

myCommands.command(
  "chef",
  "Steak delivery",
  (ctx) => ctx.reply("Steak on the plate!"),
)
  .localize(
    LanguageCodes.Russian,
    "chefpovar",
    "Стейк на тарелке!",
  );

import { LanguageCodes } from "https://deno.land/x/grammy@v1.33.0/types.ts";

myCommands.command(
  "chef",
  "Steak delivery",
  (ctx) => ctx.reply("Steak on the plate!"),
)
  .localize(
    LanguageCodes.Russian,
    "chefpovar",
    "Стейк на тарелке!",
  );

Локализация команд с помощью плагина Интернационализации

Если вы хотите, чтобы локализованные имена команд и их описания хранились в файлах .ftl, воспользуйтесь следующей идеей:

function addLocalizations(command: Command) {
  i18n.locales.forEach((locale) => {
    command.localize(
      locale,
      i18n.t(locale, `${command.name}.command`),
      i18n.t(locale, `${command.name}.description`),
    );
  });
  return command;
}

myCommands.commands.forEach(addLocalizations);

Поиск ближайшей команды

Хотя Telegram может автоматически подставляет зарегистрированные команды, иногда пользователи вводят их вручную и допускают ошибки. Плагин команд помогает справиться с этим, предлагая команду, которую пользователь, возможно, хотел ввести с самого начала. Он совместим с пользовательскими префиксами, так что о них можно не беспокоиться, и его использование довольно просто:

TypeScriptJavaScript

// Используйте расширитель для создания собственного контекста
type MyContext = Context & CommandsFlavor;

// Используйте новый контекст для инициализации бота
const bot = new Bot<MyContext>("токен");
const myCommands = new CommandGroup<MyContext>();

// ... Регистрируем команды

bot
  // Проверяем, существует ли команда
  .filter(commandNotFound(myCommands))
  // Если да, значит, она не была обработана нашими командами
  .use(async (ctx) => {
    // Мы нашли возможное совпадение
    if (ctx.commandSuggestion) {
      await ctx.reply(
        `Хм... Я не знаю такой команды. Возможно, вы имели в виду ${ctx.commandSuggestion}?`,
      );
    }

    // Похоже, ничего не похоже на то, что ввёл пользователь
    await ctx.reply("Упс... Я не знаю такой команды :/");
  });

// Используйте новый контекст для инициализации бота
const bot = new Bot("токен");
const myCommands = new CommandGroup();

// ... Регистрируем команды

bot
  // Проверяем, существует ли команда
  .filter(commandNotFound(myCommands))
  // Если да, значит, она не была обработана нашими командами
  .use(async (ctx) => {
    // Мы нашли возможное совпадение
    if (ctx.commandSuggestion) {
      await ctx.reply(
        `Хм... Я не знаю такой команды. Возможно, вы имели в виду ${ctx.commandSuggestion}?`,
      );
    }

    // Похоже, ничего не похоже на то, что ввёл пользователь
    await ctx.reply("Упс... Я не знаю такой команды :/");
  });

Под капотом, commandNotFound использует метод контекста getNearestCommand, который по умолчанию отдаёт приоритет командам, соответствующим языку пользователя. Если вы хотите отключить такое поведение, установите параметр ignoreLocalization в значение true. Можно искать по нескольким экземплярам CommandGroup, и ctx.commandSuggestion будет содержать наиболее подходящую команду, если таковая есть. Также можно установить флаг ignoreCase, чтобы игнорировать регистр при поиске похожей команды, и флаг similarityThreshold, который контролирует, насколько название команды должно быть похоже на ввод пользователя, чтобы быть рекомендованным.

Функция commandNotFound будет срабатывать только для обновлений, содержащих текст, похожий на зарегистрированные команды. Например, если у вас зарегистрированы только команды с пользовательским префиксом, например, ?, она вызовет обработчик для всего, что похоже на ваши команды, например: ?sayhi, но не для /definitely_a_command. Также работает и обратное: если у вас зарегистрированы только команды с префиксом по умолчанию, она сработает только на обновления, которые выглядят как /regular или /commands.

Рекомендуемые команды будут исходить только от экземпляров CommandGroup, переданных функции. Поэтому можно проверять команды, применяя несколько фильтров по отдельности.

Используем полученные знания для рассмотрения следующего примера:

const myCommands = new CommandGroup();
myCommands.command("dad", "calls dad", () => {}, { prefix: "?" })
  .localize("ru", "papa", "звонит папе")
  .localize("es", "papa", "llama a papa")
  .localize("fr", "pere", "appelle papa");

const otherCommands = new CommandGroup();
otherCommands.command("bread", "eat a toast", () => {})
  .localize("ru", "hleb", "съесть хлеб")
  .localize("es", "pan", "come un pan")
  .localize("fr", "pain", "manger du pain");

// Регистрируем каждую языковую группу команд

// Допустим, пользователь - француз и ввёл /Papi
bot
  // этот фильтр сработает для всех команд, похожих на '/regular' или '?custom'
  .filter(commandNotFound([myCommands, otherCommands], {
    ignoreLocalization: true,
    ignoreCase: true,
  }))
  .use(async (ctx) => {
    ctx.commandSuggestion === "?papa"; // возвращает true
  });

Если бы ignoreLocalization был ложным, мы бы получили, что ctx.commandSuggestion равен /pain. Мы могли бы добавить больше фильтров, подобных приведённому выше, с разными параметрами или CommandGroups для проверки. Возможностей множество!

Параметры команд

Существует несколько параметров, которые можно задать для каждой команды, для каждой области или глобально для экземпляра CommandGroup. Эти параметры позволяют гибко настраивать, как ваш бот обрабатывает команды.

`ignoreCase`

По умолчанию команды будут сопоставляться с пользовательским вводом с учётом регистра. Установив этот флаг, команда с именем /dandy будет воспринимать /DANDY так же, как /dandY или любую другую вариацию, различающуюся только регистром.

`targetedCommands`

При вызове команды пользователи могут упомянуть вашего бота, например: /команда@имя_бота. С помощью параметра targetedCommands можно задать, как бот будет обрабатывать такие команды. Доступны три варианта поведения:

ignored: Игнорирует команды, которые упоминают бота
optional: Обрабатывает команды как с упоминанием бота, так и без него
required: Обрабатывает только команды, в которых упоминается бот

`prefix`

В настоящее время Telegram распознает только команды, начинающиеся с символа /, и, соответственно, обработка команд в основной библиотеке grammY также выполняется с этим префиксом. Однако иногда может потребоваться использовать для бота другой префикс. Это становится возможным благодаря параметру prefix, которая позволяет плагину команд распознавать команды с указанным префиксом.

Если вам нужно получить сущности botCommand из обновления и требуется, чтобы они учитывали зарегистрированный вами пользовательский префикс, существует метод, специально предназначенный для этого — ctx.getCommandEntities(вашиКоманды), который возвращает тот же интерфейс, что и ctx.entities('bot_command').

TIP

Команды с пользовательскими префиксами не могут быть показаны в меню команд.

`matchOnlyAtStart`

При обработке команд основная библиотека grammY распознает команды только в том случае, если они начинаются с первого символа сообщения. Однако плагин команд позволяет реагировать на команды, расположенные в середине текста сообщения или в его конце — это не имеет значения! Всё, что нужно сделать — установить параметр matchOnlyAtStart на false, и плагин позаботится обо всём остальном.

Команды с использованием регулярных выражений

Эта функция подходит для тех, кто хочет задать более гибкие команды, поскольку она позволяет создавать обработчики команд на основе регулярных выражений вместо статических строк. Пример простейшего использования:

myCommands
  .command(
    /delete_([a-zA-Z]+)/,
    (ctx) => ctx.reply(`Удаление ${ctx.msg?.text?.split("_")[1]}`),
  );

Этот обработчик команды сработает как на /delete_me, так и на /delete_you, и ответит “Удаление me” в первом случае и “Удаление you” во втором, но не сработает на /delete_ или /delete_123xyz, пройдя мимо, как если бы его и не было.

Краткая информация о плагине

Название: commands
Исходник
Ссылка

Команды (commands) ​

Основное использование ​

Импортирование ​

Настройка пользовательского меню команд ​

Контекстные команды ​

Группировка команд ​

Команды с областью видимости ​

Переводы команд ​

Локализация команд с помощью плагина Интернационализации ​

Поиск ближайшей команды ​

Параметры команд ​

ignoreCase ​

targetedCommands ​

prefix ​

matchOnlyAtStart ​

Команды с использованием регулярных выражений ​

Краткая информация о плагине ​

Команды (`commands`)

Основное использование

Импортирование

Настройка пользовательского меню команд

Контекстные команды

Группировка команд

Команды с областью видимости

Переводы команд

Локализация команд с помощью плагина Интернационализации

Поиск ближайшей команды

Параметры команд

`ignoreCase`

`targetedCommands`

`prefix`

`matchOnlyAtStart`

Команды с использованием регулярных выражений

Краткая информация о плагине