Начнём издалека: что такое переменная

Представьте, что переменная — это коробка с именем. Вы кладёте туда одно значение и потом можете его достать. Например, коробка «Имя» — в ней лежит «Анна». Коробка «Возраст» — в ней «25».

📍Одна коробка = одно значение. Это самый простой вид хранения данных, и в BotMan это называется пользовательское поле.

А что если значений несколько?

Представьте, что человек добавляет товары в корзину в вашем боте-магазине. Сначала он кладёт «Кроссовки». Потом «Куртку». Потом «Шапку». Если под каждый товар заводить отдельную коробку — «Товар1», «Товар2», «Товар3» — быстро наступит хаос. А если товаров будет 10 или 20? Заводить 20 коробок вручную неудобно.
Вот тут на помощь приходит массив.

Массив — это не коробка, а полка с ячейками

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

["Кроссовки", "Куртка", "Шапка"]

Это и есть массив: три товара лежат в одном списке, по порядку. Первый — «Кроссовки», второй — «Куртка», третий — «Шапка».

Важная деталь: нумерация в программировании всегда начинается не с 1, а с 0. То есть «Кроссовки» — это элемент номер 0, «Куртка» — номер 1, «Шапка» — номер 2. Это просто такое правило, к нему быстро привыкаешь.

А зачем вообще писать в один массив, а не в отдельные поля

Смысл не в том, чтобы просто сложить значения вместе, а в том, что тогда с этим списком можно работать как с одним целым — не важно, сколько там значений: одно, пять или пятьдесят.

🫯Представьте бот-магазин без массива. Пользователь нажимает «Добавить в корзину» на кроссовках — вы записываете в поле «Товар1». Потом он добавляет куртку — поле «Товар1» уже занято, нужно «Товар2». Дальше «Товар3» и так далее. Вы заранее не знаете, сколько товаров он положит — 1 или 15, и под каждый вариант пришлось бы придумывать логику отдельно. А чтобы просто проверить «есть ли у него вообще что-то в корзине», нужно было бы проверять каждое поле по очереди.

📝С массивом всё проще: одно поле «Корзина». Каждый раз, когда пользователь жмёт «Добавить в корзину», бот делает одно и то же действие — добавить элемент в конец. Не важно, первый это товар или пятнадцатый: команда всегда одна и та же, а массив сам растёт.

И дальше это даёт готовые возможности «из коробки»:

• проверить «пусто / не пусто» одной командой, сколько бы товаров там ни было;
• узнать количество элементов, чтобы написать пользователю «У Вас 3 товара в корзине»;
• удалить конкретный товар, если пользователь передумал — без разницы, на каком он месте в списке;
• вывести весь список в сообщении одной строкой, а не перечислять вручную десяток переменных.

Главное: логика сценария не зависит от количества элементов. Один раз настраиваете «добавить в конец» / «проверить не пусто» / «показать список» — и это одинаково работает что для 1 товара, что для 50.

А что такое объект

Иногда одного значения на элемент недостаточно — нужно сразу несколько связанных свойств. Например, товар — это не просто название, а ещё и цена. Тогда вместо простого текста или числа элементом массива становится объект: набор пар «свойство — значение» в одной ячейке.

Разберём разницу на примере.

Вариант 1️⃣ — два разных элемента массива:

["Кроссовки", 2990]

Тут в шкафу две отдельные полки: на первой лежит слово «Кроссовки», на второй — число 2990. Бот не понимает, что они связаны друг с другом — это просто два самостоятельных значения в списке.

Вариант 2️⃣ — объект:

{"name": "Кроссовки", "price": 2990}

А тут — одна полка (один элемент массива), но на этой полке лежит не просто слово, а мини-карточка с двумя подписанными полями:

• поле name (название) = «Кроссовки»;
• поле price (цена) = 2990.

Это как бирка на товаре в магазине: на одной бирке сразу написано и название, и цена — это одна бирка, просто с двумя строчками на ней.

Так вот, {"name": "Кроссовки", "price": 2990} — это весь этот объект целиком, и он и есть один элемент массива. А name и price — это не отдельные элементы, а просто подписанные «ячейки» внутри этой одной карточки.

Поэтому когда у Вас несколько товаров, каждый товар — это одна карточка (один элемент), и весь список карточек выглядит так:

[
  {"name": "Кроссовки", "price": 2990},
  {"name": "Куртка", "price": 5990}
]

Здесь в массиве два элемента (две карточки-товара), а не четыре. Каждая карточка внутри себя хранит и название, и цену.

Удобно, когда нужно хранить не просто список названий, а список товаров с ценой, список записей с датой и именем и так далее.

Примеры массивов из практики бота

• Корзина покупок — товары, которые пользователь добавил в свой заказ.
• Список выбранных дат — если человек записывается сразу на несколько занятий.
• Список городов доставки — общий перечень, который бот показывает всем.
• Каталог с ценами — список объектов вида {"name": "...", "price": ...}, где у каждой позиции сразу есть и название, и стоимость.

Ещё несколько важных моментов

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

Как объект отвечает на вопрос «содержит ли массив значение». Если Вы проверяете, есть ли в массиве объектов какое-то значение, бот ищет совпадение по любому полю карточки, а не только по одному конкретному. То есть для объекта {"name": "Кроссовки", "price": 2990} и проверка на «Кроссовки», и проверка на «2990» — обе дадут «да», потому что оба значения лежат внутри этой карточки.

Как массив выглядит в сообщении пользователю. Простой массив (без объектов) выводится обычным нумерованным списком:

1. Кроссовки
2. Куртка
3. Шапка

А вот массив объектов — умнее. Если в карточке есть поля name (название), quantity (количество) и price (цена), бот сам соберёт их в понятную строку. Например, объект

{"name": "Кроссовки", "quantity": 2, "price": 2990}

в сообщении превратится в:

1. Кроссовки x2 — 2990

Здесь «x2» — это как раз значение поля quantity, то есть «взято 2 штуки». Если поля quantity в объекте нет, бот просто выведет название и цену без «x2».

Так пользователь видит понятную строку вместо сырого JSON вида {"name": "Кроссовки", "quantity": 2, "price": 2990}.

Четыре вида хранилищ в BotMan — чтобы не путаться

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

1. Пользовательское поле — Ваша личная тумбочка в своей квартире

Одно значение, и оно своё у каждого пользователя. У Анны в тумбочке лежит «10» (её бюджет), у Петра — «100» (его бюджет). Тумбочки разные, значения разные, друг на друга не влияют.

2. Пользовательский массив — Ваш личный шкаф с несколькими полками, тоже в своей квартире

То же самое, только вместо одной вещи хранится сразу несколько — и это по-прежнему личное, только у этого человека. Корзина Анны — это её корзина, у Петра своя, отдельная.

3. Глобальная переменная — один почтовый ящик на весь подъезд

Значение одно, и оно общее для всех. Если кто-то его изменил — увидят все жители подъезда (все подписчики бота). Пример: счётчик «сколько промокодов уже выдано» — он один на весь бот, а не у каждого свой.

4. Глобальный массив — общий шкаф в подъезде, которым пользуются все

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

Важно: раз глобальный массив видят все, туда нельзя класть личные данные конкретного человека (например, его телефон или его личную корзину) — их увидят и остальные.

А что такое системные переменные

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

Таблица для быстрой сверки

Главное, что стоит запомнить

• Обычное поле — одно значение.
• Массив — несколько значений, пронумерованных по порядку, начиная с нуля.
• Объект — это когда у одного элемента массива сразу несколько связанных свойств, например название и цена.
• «Пользовательское» — значит своё у каждого человека.
• «Глобальное» — значит одно на всех, будьте аккуратны с личными данными.
• Системные переменные создавать не нужно — бот сам их знает.

Если запомнить только одну вещь — пусть это будет: массив — это когда нужно хранить не одно значение, а список.

Как создать массив, как правильно записать значение в формате JSON и какие операции с ним доступны — читайте в статьях «Массивы: создание, формат и использование» и «Действия с массивами».