Keyboard

Эта клавиатура отображается под полем ввода и также известна как Reply/Custom Keyboard. Представляет собой кастомную клавиатуру с вариантами ответа (смотрите Введение в ботов для деталей и примеров).

См. также API Reference

Импорт

С GramIO

import { Keyboard } from "gramio";

Без GramIO

import { Keyboard } from "@gramio/keyboards";

Кнопки (Документация)

Кнопки - это методы, которые собирают клавиатуру для вас.

text

Текстовая кнопка. Будет отправлена как сообщение при нажатии на кнопку.

new Keyboard().text("текст кнопки");

requestUsers

Кнопка запроса пользователей. Нажатие на кнопку откроет список подходящих пользователей. Идентификаторы выбранных пользователей будут отправлены боту в служебном сообщении users_shared. Доступно только в приватных чатах. Второй параметр - это 32-битный идентификатор запроса, который будет получен обратно в объекте UsersShared. Должен быть уникальным в пределах сообщения.

new Keyboard().requestUsers("текст кнопки", 228, {
    user_is_premium: true,
});

Подробнее о параметрах в документации

requestChats

Кнопка запроса чатов. Нажатие на кнопку откроет список подходящих чатов. Нажатие на чат отправит его идентификатор боту в служебном сообщении chat_shared. Доступно только в приватных чатах. Второй параметр - это 32-битный идентификатор запроса, который будет получен обратно в объекте ChatShared. Должен быть уникальным в пределах сообщения.

new Keyboard().requestChat("gramio", 255, {
    chat_is_forum: true,
});

WARNING

По умолчанию параметр chat_is_channel установлен в false!

Подробнее о параметрах в документации

requestPoll

Кнопка запроса опроса. Нажатие на кнопку откроет список подходящих пользователей. Идентификаторы выбранных пользователей будут отправлены боту в служебном сообщении users_shared. Доступно только в приватных чатах.

new Keyboard().requestPoll("текст кнопки", "quiz");

Подробнее о параметрах в документации

requestLocation

Кнопка запроса местоположения пользователя. Текущее местоположение пользователя будет отправлено при нажатии на кнопку. Доступно только в приватных чатах.

new Keyboard().requestLocation("текст кнопки");

requestContact

Кнопка запроса контакта. Номер телефона пользователя будет отправлен как контакт при нажатии на кнопку. Доступно только в приватных чатах.

new Keyboard().requestContact("текст кнопки");

webApp

Кнопка webApp. Описанное Веб-приложение будет запущено при нажатии на кнопку. Веб-приложение сможет отправить служебное сообщение web_app_data. Доступно только в приватных чатах.

new Keyboard().webApp("текст кнопки", "https://...");

Параметры (Документация)

Эти параметры отвечают за настройки кнопок.

resized

Запрашивает у клиентов изменение размера клавиатуры по вертикали для оптимального размещения (например, уменьшить клавиатуру, если есть всего две строки кнопок). Если false, то кастомная клавиатура всегда имеет такую же высоту, как и стандартная клавиатура приложения. По умолчанию true.

new Keyboard().text("какой-то текст").resized(); // для включения
new Keyboard().text("какой-то текст").resized(false); // для отключения

WARNING

Размер кнопок по умолчанию изменяется! Чтобы отменить это, используйте .resized(false)

oneTime

Запрашивает у клиентов скрытие клавиатуры, как только она была использована. Клавиатура все еще будет доступна, но клиенты автоматически отобразят обычную буквенную клавиатуру в чате - пользователь может нажать специальную кнопку в поле ввода, чтобы снова увидеть кастомную клавиатуру. По умолчанию false.

new Keyboard().text("какой-то текст").oneTime(); // для включения
new Keyboard().text("какой-то текст").oneTime(false); // для отключения

persistent

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

new Keyboard().text("какой-то текст").persistent(); // для включения
new Keyboard().text("какой-то текст").persistent(false); // для отключения

selective

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

Цели:

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

Пример: Пользователь запрашивает изменение языка бота, бот отвечает на запрос клавиатурой для выбора нового языка. Другие пользователи в группе не видят клавиатуру. По умолчанию false.

new Keyboard().text("какой-то текст").selective(); // для включения
new Keyboard().text("какой-то текст").selective(false); // для отключения

placeholder

Заполнитель, отображаемый в поле ввода, когда клавиатура активна. 1-64 символа. По умолчанию не отображается.

new Keyboard().text("какой-то текст").placeholder("какой-то текст"); // для включения
new Keyboard().text("какой-то текст").placeholder(); // для отключения

Помощники

Методы, которые помогают вам создать клавиатуру.

row

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

new Keyboard().text("первая строка").row().text("вторая строка");

columns

Позволяет ограничить количество столбцов в клавиатуре.

new Keyboard()
    .columns(1)
    .text("первая строка")
    .text("вторая строка")
    .text("третья строка");

wrap

Кастомный обработчик, который управляет переносом строк.

new Keyboard()
    .wrap(({ button }) => button.text === "вторая строка")
    .text("первая строка")
    .text("первая строка")
    .text("вторая строка");

обработчик имеет вид

(options: { button: T; index: number; row: T[]; rowIndex: number }) => boolean;

pattern

Массив с количеством столбцов в каждой строке. Позволяет установить «шаблон».

new Keyboard()
    .pattern([1, 3, 2])
    .text("1")
    .text("2")
    .text("2")
    .text("2")
    .text("3")
    .text("3");

filter

Обработчик, который помогает фильтровать кнопки клавиатуры.

new Keyboard()
    .filter(({ button }) => button.text !== "скрытая")
    .text("проходит")
    .text("скрытая")
    .text("проходит");

add

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

const labels = ["какие-то", "кнопки"];

new Keyboard()
    .add({ text: "сырая кнопка" })
    .add(Keyboard.text("сырая кнопка через Keyboard.text"))
    .add(...labels.map((x) => Keyboard.text(x)));

addIf

Позволяет динамически подставлять кнопки в зависимости от чего-либо.

const labels = ["какие-то", "кнопки"];
const isAdmin = true;

new Keyboard()
    .addIf(1 === 2, { text: "сырая кнопка" })
    .addIf(isAdmin, Keyboard.text("сырая кнопка через Keyboard.text"))
    .addIf(
        ({ index, rowIndex }) => rowIndex === index,
        ...labels.map((x) => Keyboard.text(x))
    );

обработчик имеет вид

(options: { rowIndex: number; index: number }) => boolean;

matrix

Позволяет создать матрицу кнопок.

import { randomInt } from "node:crypto";

const bomb = [randomInt(0, 9), randomInt(0, 9)] as const;

new Keyboard().matrix(10, 10, ({ rowIndex, index }) =>
    Keyboard.text(rowIndex === bomb[0] && index === bomb[1] ? "💣" : "ㅤ")
);

Результатом является клавиатура с бомбой на случайной кнопке.

обработчик имеет вид

(options: { index: number; rowIndex: number }) => T;

combine

Позволяет объединять клавиатуры. Объединяются только клавиатуры. Вам нужно вызвать метод .row() для переноса строки после объединения.

new Keyboard()
    .combine(new Keyboard().text("первая"))
    .row()
    .combine(new Keyboard().text("вторая").row().text("третья"));

Обновления

Хуки

Клавиатуры

Файлы

Telegram Web Apps

Keyboard

Импорт

С GramIO

Без GramIO

Кнопки (Документация)

text

requestUsers

requestChats

requestPoll

requestLocation

requestContact

webApp

Параметры (Документация)

resized

oneTime

persistent

selective

placeholder

Помощники

row

columns

wrap

pattern

filter

add

addIf

matrix

combine

Keyboard ​

Импорт ​

С GramIO ​

Без GramIO ​

Кнопки (Документация) ​

text ​

requestUsers ​

requestChats ​

requestPoll ​

requestLocation ​

requestContact ​

webApp ​

Параметры (Документация) ​

resized ​

oneTime ​

persistent ​

selective ​

placeholder ​

Помощники ​

row ​

columns ​

wrap ​

pattern ​

filter ​

add ​

addIf ​

matrix ​

combine ​

Keyboard

Импорт

С GramIO

Без GramIO

Кнопки (Документация)

text

requestUsers

requestChats

requestPoll

requestLocation

requestContact

webApp

Параметры (Документация)

resized

oneTime

persistent

selective

placeholder

Помощники

row

columns

wrap

pattern

filter

add

addIf

matrix

combine