EnotPRO Logo EnotPRO

AddVarCloud

AddVarCloud — изменяет значение облачной переменной, не заменяя его полностью.

📝 Назначение

Используется для накопления данных: счётчиков, списков, истории действий. В отличие от SetVarCloud, эта реакция изменяет существующее значение, а не перезаписывает.

💡 Совет: Это идеальный выбор для:

  • Счётчиков нажатий (+1 каждый раз)
  • Накопления суммы покупок
  • Добавления элементов в массив (история заказов)
  • Объединения объектов (дополнение профиля)

🟢 Важно: Если переменная не существует, AddVarCloud создаст её — но не просто запишет значение, а добавит его к нулевому значению. Подробнее — в разделе «Добавление в несуществующую переменную» ниже.

🔄 Поведение в зависимости от типа

Что произойдёт, зависит от типа текущего значения переменной:

Текущее значение Что делает Пример
Целое число Прибавляет Было 10, добавить 3 → 13
Дробное число Прибавляет Было 10.5, добавить 2.3 → 12.8
Строка Добавляет текст в конец Было Привет, добавить , мир → Привет, мир
Список Добавляет элемент в конец Было [1,2], добавить 3 → [1,2,3]
Объект Объединяет по ключам (поверхностно) {"a":1} + {"b":2} → {"a":1, "b":2}
Логическое Переключает на противоположное Было true → станет false

⚠️ Особенность логического типа: Добавление к логическому значению — это переключение. Само добавляемое значение при этом не учитывается: и true, и false дадут результат, противоположный текущему.

⚠️ Важно: Результат должен остаться того же типа, что и сама переменная. Например, если к числовой переменной добавить текст abc, результат стал бы строкой — такая операция завершится ошибкой, и значение не сохранится.

📍 Подсказка: Если у переменной настроен срок хранения и он истёк, добавление выполняется к нулевому значению — старое значение уже не учитывается.

⚙️ Параметры

Параметр Тип Обязательный Описание
Тип переменной Выбор ✅ Да person, member, chat, global, dynamic
Название Строка ✅ Да Имя переменной (только латиница, цифры, нижнее подчеркивание)
Значение Зависит от типа ❌ Нет Значение для добавления. Можно оставить пустым — получится нулевое значение выбранного типа
Тип данных Выбор ✅ Да Как понимать добавляемое значение: bool, number, float, string, json, yaml, array json, array yaml
Слияние списков Переключатель ❌ Нет Как добавлять список к списку. По умолчанию выключен
ID пользователя Integer ❌ Нет Для типа person. По умолчанию — текущий пользователь
ID чата Integer ❌ Нет Для типов member и chat. По умолчанию — текущий чат

📍 Подсказка: Тип данных здесь описывает добавляемое значение, а не саму переменную — её тип задан в админке при создании. Обычно они совпадают, но, например, к списку можно добавлять и число (тогда оно станет очередным элементом).

🔗 Слияние списков

Переключатель имеет смысл только когда и переменная, и добавляемое значение — списки.

Слияние списков Что делает Пример
Выключено Добавляемый список становится одним элементом [1,2] + [3,4] → [1,2,[3,4]]
Включено Элементы добавляются подряд [1,2] + [3,4] → [1,2,3,4]

⚠️ Важно: На объекты переключатель не влияет: объекты всегда объединяются по ключам. Если нужна полная замена — это SetVarCloud.

🆕 Добавление в несуществующую переменную

Если записи ещё нет (или её значение пустое), добавление выполняется к нулевому значению. Результат:

Тип добавляемого значения Что получится
number, float, string Само значение: 0 + 5 → 5
json, yaml (объект) Сам объект
array json, array yaml при выключенном слиянии Список внутри списка: [] + [1,2] → [[1,2]]
array json, array yaml при включённом слиянии Список как есть: [] + [1,2] → [1,2]
bool Всегда true — переключение отсчитывается от false

🧪 Примеры

Пример 1: Счётчик нажатий кнопки

Задача: При каждом нажатии на кнопку увеличивать счётчик.

Реакция AddVarCloud:

  • Тип: person
  • Название: button_clicks
  • Значение: 1
  • Тип данных: number

Результат:

  • Первое нажатие → переменная создана, значение 1
  • Второе нажатие → было 1, стало 2
  • Третье нажатие → было 2, стало 3

Отображение пользователю:

Вы нажали кнопку !{varcloud|name: button_clicks|default: 0} раз

Пример 2: Накопление суммы покупок

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

Реакция AddVarCloud:

  • Тип: person
  • Название: total_spent
  • Значение: ${purchase_amount} (например, 150.50)
  • Тип данных: float

Результат:

  • Было 1000.00, добавить 150.50 → стало 1150.50

Пример 3: Добавление элемента в массив (история заказов)

Задача: Сохранять ID всех заказов пользователя в массиве.

Реакция AddVarCloud:

  • Тип: person
  • Название: orders (переменная типа «список» в админке)
  • Значение: [${order_id}] (например, [12345])
  • Тип данных: array json
  • Слияние списков: включено

Результат:

  • Первый заказ → записи не было, стало [12345]
  • Второй заказ → было [12345], стало [12345, 12346]
  • Третий заказ → было [12345, 12346], стало [12345, 12346, 12347]

⚠️ Важно: Если слияние выключить, добавляемый список ляжет одним элементом — получится [[12345], [12346]]. Второй рабочий вариант — добавлять само число с типом number: к существующему списку оно тоже допишется элементом, но если записи ещё нет, вместо списка создастся просто число.

Проверка количества заказов:

У вас !{list.len|list: !{varcloud|name: orders|default: []}} заказов

Пример 4: Добавление текста в конец строки (лог действий)

Задача: Вести лог действий пользователя.

Реакция AddVarCloud:

  • Тип: person
  • Название: action_log
  • Значение: \n!{time|output_format: DD.MM.YYYY hh:mm} - Нажата кнопка "Помощь"
  • Тип данных: string

Результат:

  • Первое действие → 2026.06.02 14:30 - Нажата кнопка "Помощь"
  • Второе действие → 2026.06.02 14:30 - Нажата кнопка "Помощь"\n2026.06.02 14:35 - Запрошен баланс

Пример 5: Объединение JSON-объектов (дополнение профиля)

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

Шаг 1 (форма «Имя и возраст»):

  • Тип: person
  • Название: profile
  • Значение: {"name": "Иван", "age": 30}
  • Тип данных: json

Шаг 2 (форма «Город и телефон»):

  • Тип: person
  • Название: profile
  • Значение: {"city": "Москва", "phone": "+79991234567"}
  • Тип данных: json

Результат:

{
  "name": "Иван",
  "age": 30,
  "city": "Москва",
  "phone": "+79991234567"
}

Пример 6: Добавление для другого пользователя (администратор)

Задача: Администратор начисляет бонус пользователю.

Реакция AddVarCloud:

  • Тип: person
  • Название: bonus
  • Значение: 100
  • Тип данных: number
  • ID пользователя: ${target_user.id}

Результат: У пользователя target_user переменная bonus увеличилась на 100.

🔄 Разница между AddVarCloud и SetVarCloud

Операция AddVarCloud SetVarCloud
Число 10, значение 5 Будет 15 (прибавит) Будет 5 (заменит)
Строка A, значение B Будет AB (допишет в конец) Будет B (заменит)
Список [1,2], значение 3 (тип number) Будет [1,2,3] (добавит элемент) Ошибка: 3 не список
Список [1,2], значение [3,4] (тип array json) Будет [1,2,[3,4]], а со слиянием — [1,2,3,4] Будет [3,4] (заменит)
Объект {"a":1}, значение {"b":2} Будет {"a":1, "b":2} (объединит) Будет {"b":2} (заменит)
Логическое true, значение false Будет false (переключит) Будет false (заменит)

🔗 Связанные реакции

🔗 Связанные разделы

© 2025 EnotPRO. Все права защищены.