Перейти к содержанию

Меню

Ваше меню представляет собой дерево узлов под ключом верхнего уровня menu. Есть два виды узла:

Если эти слова новые, сначала прочтите Основные понятия. Точный список каждого поля см. Конфигурация → Меню.

Плоское меню

Простейшее меню представляет собой список кнопок без вложенности:

Сделать меню с тремя кнопками

Three buttons, no categories
menu:
  - name: Uptime
    type: button
    function: command
    command: "uptime"

  - name: Free memory
    type: button
    function: command
    command: "free -h"

  - name: Disk usage
    type: button
    function: command
    command: "df -h"

Отправьте /start в Telegram. Вы увидите свое меню.

Группировка по категориям

По мере роста вашего меню группируйте связанные действия по категориям. Категория показывает свое items при нажатии. Кнопка «Домой» всегда доступна. Кнопка «Назад» появляется только внутри категория.

Группировать кнопки по категориям

System and Services categories
menu:
  - name: System
    type: category
    icon: "💻"
    items:
      - name: Uptime
        type: button
        function: command
        command: "uptime"

      - name: Free memory
        type: button
        function: command
        command: "free -h"

  - name: Services
    type: category
    icon: "🔧"
    items:
      - name: Restart nginx
        type: button
        function: command
        command: "systemctl restart nginx"
        confirm: true

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

Имена должны быть уникальными среди соседних элементов

Два узла одного и того же родителя не могут иметь одно и то же имя (при сравнении регистр игнорируется). Это нормально, потому что они находятся в разных категориях:

Повторное использование имени под разными родителями

The same name under two parents
menu:
  - name: Web
    type: category
    items:
      - name: Restart          # допустимо
        type: button
        function: command
        command: "systemctl restart nginx"
  - name: Database
    type: category
    items:
      - name: Restart          # допустимо, другой родитель
        type: button
        function: command
        command: "systemctl restart postgresql"

Значки

icon — это необязательный смайлик, отображаемый перед именем. Это чисто косметический характер.

Эта кнопка перезагружает компьютер

A button with an emoji icon
- name: Reboot
  type: button
  icon: "🔁"
  function: command
  command: "reboot"
  confirm: true

Выберите простой и распространенный смайлик

Из-за нескольких смайлов на некоторых телефонах текст кнопки обрезается или выходит за пределы кнопка. Если кнопка выглядит отрезанной, попробуйте использовать для нее другой смайлик.

Как выглядит меню Telegram

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

  • Домой — всегда первая кнопка на каждом экране. Нажмите на него, чтобы вернуться к первый экран.
  • Назад появляется, когда вы находитесь внутри категории.
  • $ >_ Выполнение команды появляется, когда включен enable_run_command (см. ниже).
  • По умолчанию элементы располагаются по два в ряду. Категория может изменить это с помощью columns. Если на экране много элементов, Предыдущий и Следующий позволяют пролистывать их.
  • Кнопки с confirm: true задают вопрос «Да/Отмена» перед запуском.

Названия меню используются повторно, вывод остается

Новый заголовок меню (Главная, категория, страница) заменяет предыдущий, поэтому чат не заполняется пустыми экранами. Линия Работающая и вывод команды остается в чате, чтобы вы все равно могли прочитать, что последовало за вами откройте меню еще раз.

Результат остаётся сообщениями или приходит файлом

Короткий вывод команды остаётся в чате блоком кода. Более длинный результат может прийти несколькими ответными сообщениями или одним файлом .txt — это зависит от output. Последнее сообщение (или файл) сохраняет те же кнопки, что и страница, на которой вы находились, поэтому Назад по-прежнему означает выйти из этой категории. См. Управление выводом.

Подтверждение

Добавьте confirm: true к любой кнопке, чтобы требовалось второе нажатие («Вы уверены?»). прежде чем он запустится. Используйте его для чего-нибудь разрушительного. См. Подтверждение для концепции.

Эта кнопка останавливает службу

A button that asks first
- name: Stop nginx
  type: button
  function: command
  command: "systemctl stop nginx"
  confirm: true

Срок действия запроса на подтверждение истекает через некоторое время (по умолчанию 5 минут). Измените его с помощью confirm_ttl; см. Конфигурация → Корневые поля.

Переопределения для каждой кнопки

Некоторые глобальные настройки можно переопределить с помощью одной кнопки:

Назначьте одной кнопке собственные настройки

One button with its own timeout, folder, and variables
- name: Long backup
  type: button
  function: command
  command: "/usr/local/bin/backup.sh"
  timeout: "10m"          # может выполняться дольше общего тайм-аута
  workdir: "/var/backups" # запускать здесь
  env:
    BACKUP_MODE: "full"   # дополнительная переменная окружения для этой команды

Полный список полей смотрите в Конфигурация → Меню.

Схема размещения

menu_columns задает количество кнопок элементов, отображаемых в строке (по умолчанию 2). Категория может переопределить его с помощью columns. Когда число элементов превышает page_size (по умолчанию 8), меню разбивается на страницы. Кнопки «Назад» и «Далее» позволяют переходить между ними. См. Конфигурация → Корневые поля.

Выполнение команды

Если вы установите enable_run_command: true в корне вашей конфигурации, **`$

_ Выполнить команду** остается в меню (после кнопки «Вернуться в категорию», или после «Домой» на первом экране). Нажмите её, а затем отправьте команду оболочки, которую хотите выполнить. Бот использует ту же оболочку, тайм-аут, рабочий каталог и настройки [вывода](../output-control.md), что и другие кнопки. У «Выполнить команду» нет своегоoutput`, поэтому она всегда следует корневой настройке.

Команда «Домой» или «Назад» отменяет запрос, ничего не запуская. Это выключено по умолчанию. См. Конфигурация → Корневые поля.

Это передает всю машину

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

По одной команде за раз

Ваши команды выполняются одна за другой, а не рядом.

Второй кран ждет своей очереди

Если вы нажмете вторую кнопку, пока первая еще работает, вторая ждет, а затем работает самостоятельно. Вы увидите строку Работает, как только она начинается. Это не позволит двум вашим касаниям ссориться из-за одного и того же. сервис или файл. Другие люди, использующие бота, не задерживаются вашими действиями. команда; у каждого своя очередь.

Что происходит при нажатии кнопки

Каждая кнопка указывает на функцию через поле function. Кнопка в приведенных выше примерах используется встроенная функция command. Чтобы понять функции, встроенные и пользовательские, а как добавить свои, читайте Функции.

Похожие страницы