---
url: /templates/storage/attributes.md
description: >-
  Атрибуты участников и чата — как хранить балансы, счетчики и анкеты между
  вызовами команд.
---

# Атрибуты

<p class="lead">Атрибут — это именованное значение, которое бот запоминает надолго: баланс монет участника, количество побед, выбранный режим, дата последнего бонуса. Атрибуты бывают у каждого участника и у чата в целом.</p>

## Атрибуты участника { #member }

Атрибут получают по ключу — названию, которое вы придумываете сами:

```template
{% set coins = member.getAttribute('coins') %}
У тебя {{ coins.value ?: 0 }} монет.
```

То же можно записать короче: `member.attributes.coins`.

`getAttribute` возвращает объект [MemberAttribute](/reference/member-attribute), у которого есть значение и методы:

| Что | Описание |
|---|---|
| `.value` | Текущее значение. Если атрибут еще не записывали — пусто |
| `.updatedAt` | Когда значение последний раз меняли |
| `.update(значение)` | Записать новое значение |
| `.increment(n)` | Прибавить `n` и вернуть новое значение |
| `.decrement(n)` | Вычесть `n` и вернуть новое значение |
| `.clear()` | Удалить атрибут |

Если значение не число, `increment` и `decrement` считают его нулем.

```template
{% set wins = member.getAttribute('wins').increment(1) %}
🏆 Победа! Всего побед: {{ wins }}
```

## Атрибуты чата { #chat }

Общие для всего чата значения хранятся у бота или у чата — это одно и то же:

```template
{% set counter = bot.getAttribute('greetings') %}
{% do counter.increment(1) %}
Это {{ counter.value }}-е приветствие в чате.
```

`chat.getAttribute('greetings')` вернет тот же атрибут.

## Что можно хранить { #values }

| Тип | Как хранится |
|---|---|
| Число | Как есть |
| Строка | До 4 КБ |
| Логическое | `true` / `false` (строки `'true'` и `'false'` тоже превращаются в логические) |
| Участник, роль бота, топик | Ссылкой по ID: при чтении вернется сам объект |

```template
{% do member.getAttribute('best_friend').update(arguments.targetMember) %}
Лучший друг: {{ member.getAttribute('best_friend').value }}
```

## Массовая очистка { #clear }

| Метод | Что делает |
|---|---|
| `chat.clearAttributes('coins')` | Удалить атрибут `coins` у всех участников |
| `chat.clearAllAttributes()` | Удалить все атрибуты в чате |

::: danger Очистку не отменить
Удаленные атрибуты восстановить нельзя. Делайте массовую очистку отдельной командой, доступной только администраторам.
:::

## Пример: экономика { #economy }

Команда `!баланс` показывает монеты, `!перевести @кому сумма` переводит их другому участнику:

```template
{% set target = arguments.targetMember %}
{% set amount = arguments.get(2) %}
{% require target returning 'Кому переводим? !перевести @anna 50' %}
{% require target.id != member.id returning 'Нельзя перевести самому себе' %}
{% require (amount is number) and amount > 0 returning 'Укажи сумму положительным числом' %}
{% set mine = member.getAttribute('coins') %}
{% require (mine.value ?: 0) >= amount returning 'Недостаточно монет' %}
{% do mine.decrement(amount) %}
{% set theirs = target.getAttribute('coins').increment(amount) %}
💸 {{ member }} перевел {{ amount }} 🪙 участнику {{ target }}. У получателя теперь {{ theirs }} 🪙.
```

::: tip Топ по монетам
Атрибуты удобны для данных одного участника, но из них нельзя быстро собрать «топ-10». Если нужен рейтинг, дублируйте значение в [индекс чата](./indexes).
:::

## Ограничения { #limits }

* За одно выполнение — не больше 5 разных ключей (атрибуты участников и чата вместе).
* В чате — до 10 000 ключей.
* Значение — до 4 КБ.
* Атрибуты меняет только бот — по вашим шаблонам. Просмотр атрибутов в панели появится позже.