Создание команд с помощью `@command`¶

Декоратор @command — это основной способ регистрации команд, на которые будут реагировать пользователи.

Аргументы декоратора `@command`¶

@command(
    command: Optional[str] = None,
    aliases: Optional[List[str]] = None,
    doc: Optional[str] = None,
    enabled: Optional[Union[str, bool]] = None
)

command: Имя команды. Если не указано, используется имя функции.
aliases: Список (list) строковых псевдонимов для команды. Например, aliases=["e", "exec"].
doc: Ключ для строки с описанием команды из словаря strings (или само описание). Это описание будет видно в меню .chelp, в меню установки плагина и в списке плагинов.
enabled: Позволяет связать состояние команды (включена/выключена) с настройкой плагина.
- bool: True (по умолчанию) или False.
- str: Ключ булевой настройки (Switch) из create_settings(). Команда будет активна, только если эта настройка включена.

Объект `CactusUtils.Command`¶

В функцию команды всегда передается объект CactusUtils.Command, который содержит всю необходимую информацию о вызове.

cmd.command: str: Имя команды или псевдоним, который был использован.
cmd.args: List[str]: Список разделенных аргументов после команды.
cmd.raw_args: str: Все, что идет после команды, в виде одной строки.
cmd.text: str: Полный текст исходного сообщения.
cmd.params: Any: Объект с параметрами исходного сообщения (peer, replyToMsg и т.д.).
cmd.answer(text: str, **kwargs): Быстрый способ отправить ответ. Алиас для CactusUtils.send_message(cmd.params.peer, text, replyToTopMsg=cmd.params.replyToTopMsg, **kwargs)
cmd.html() -> str: Возвращает текст исходного сообщения с HTML-разметкой.
cmd.markdown() -> str: Возвращает текст исходного сообщения с Markdown-разметкой.

Примеры¶

1. Простая команда с псевдонимами и описанием

class MyPlugin(CactusUtils.Plugin):
    strings = {
        "en": {
            "PING_DOC": "Checks if the plugin is working.",
            "pong": "🏓 PONG!",
        },
        "ru": {
            "PING_DOC": "Проверяет, работает ли плагин.",
            "pong": "🏓 ПОНГ!",
        }
    }

    @command(aliases=["p"], doc="PING_DOC")
    def ping(self, cmd: CactusUtils.Command):
        # Используем `answer` для отправки ответа
        cmd.answer(self.string("pong"))

        return HookResult(strategy=HookStrategy.CANCEL)
    
    def _on_sent_ping(self, params: CactusUtils.Inline.CallbackParams):
        # Редактируем сообщение
        params.edit(self.string("pong"))

        # Удаляем сообщение через 5 секунд
        threading.Timer(5, lambda: params.delete()).start()

    @command(aliases=["p"], doc="PING_DOC")
    def ping2(self, cmd: CactusUtils.Command):
        # Используем `on_sent` для редактирования сообщения после отправки
        cmd.answer("...", on_sent=lambda params: self._on_sent_ping(params))

        return HookResult(strategy=HookStrategy.CANCEL)
    

Вызов: .ping или .p.

В .chelp: .ping - Checks if the plugin is working. (или pong - Проверяет, работает ли плагин.)

2. Команда с аргументами

class MyPlugin(CactusUtils.Plugin):
    @command(doc="Повторяет ваши слова")
    def echo(self, cmd: CactusUtils.Command):
        if not cmd.raw_args:
            cmd.answer("Мне нечего повторять.")
            return HookResult(strategy=HookStrategy.CANCEL)
        
        # Используем HTML-безопасную версию для избежания инъекций
        safe_text = self.utils.escape_html(cmd.raw_args)
        cmd.answer(f"Вы сказали: <b>{safe_text}</b>")

        return HookResult(strategy=HookStrategy.CANCEL)

Вызов: .echo Привет, мир! Ответ: Вы сказали: <b>Привет, мир!</b>

3. Команда, зависящая от настройки

class MyPlugin(CactusUtils.Plugin):
    def create_settings(self):
        # В настройках плагина
        return [Switch(key="extra_feature_enabled", text="Включить фичу X", default=False)]

    @command(doc="Команда для фичи X", enabled="extra_feature_enabled")
    def extra_cmd(self, cmd: CactusUtils.Command):
        cmd.answer("Фича X работает!")

        return HookResult(strategy=HookStrategy.CANCEL)

Эта команда будет работать, только если пользователь включит опцию «Включить фичу X» в настройках вашего плагина.

4. Команда, которая ожидает отправления сообщения, а после срабатывает

class MyPlugin(CactusUtils.Plugin):
    def _on_sent(self, params: CactusUtils.Inline.CallbackParams):
        # Вы можете сделать что угодно с сообщением, которое отправилось

        # Вы можете изменить текст
        params.edit("Edited message")

        # Вы можете отправить сообщение в ответ на исходное
        self.utils.send_message(params.message.getDialogId(), "Ответ на исходное сообщение", replyToMsg=params.message)

        # Вы можете удалить сообщение
        params.delete()

    @command()
    def test(self, cmd: CactusUtils.Command):
        cmd.answer("Ожидайте...", on_sent=lambda params: self._on_sent(params))

        return HookResult(strategy=HookStrategy.CANCEL)

Создание команд с помощью @command¶

Аргументы декоратора @command¶

Объект CactusUtils.Command¶

Примеры¶

Создание команд с помощью `@command`¶

Аргументы декоратора `@command`¶

Объект `CactusUtils.Command`¶