# Рейтинги

← [Назад к разделу «Модули»](README.md)

Модуль `ratings` выводит шкалу оценок для документов и других объектов. Голоса
хранит обязательный модуль [Взаимодействия](interactions.md).

## Вставка виджета

Для текущего документа:

```text
[mod_rating]
```

Для явно указанного объекта:

```text
[mod_rating:document:145]
[mod_rating:article:news-2026-07]
```

Формат: `[mod_rating:ТИП:КЛЮЧ]`. Тип должен присутствовать в настройке
**Типы объектов**. Для обычных документов используется `document`, ключом
служит ID. Без явных аргументов ID берётся из контекста текущего документа.

## Теги шаблона

| Тег | Значение |
| --- | --- |
| `[tag:label]` | Настраиваемое название рейтинга. |
| `[tag:average]` | Средняя оценка с одним знаком после точки. |
| `[tag:count]` | Число пользователей, поставивших оценку. |
| `[tag:scale]` | Максимум шкалы, от 2 до 10. |
| `[tag:own]` | Оценка текущего посетителя или пустая строка. |
| `[tag:buttons]` | Готовые доступные кнопки шкалы с ARIA-атрибутами. |

Внешний контейнер, endpoint, CSRF и служебное сообщение добавляет renderer.
Не удаляйте `[tag:buttons]`, если виджет должен принимать оценки.

## API и поведение

Виджет отправляет оценку в общий endpoint:

```text
POST /api/v1/interactions/document/145/rating
```

Полезная нагрузка: `operation=set`, `action=rating`, `value=1..scale`. Повторная
оценка того же actor обновляет старое значение, а не создаёт второй голос.

Гостевые оценки включаются отдельно. Rate limit задаёт число изменений в
минуту. Если тип объекта не разрешён, renderer не должен использоваться для
него, а API отклонит запись правилами канала.

Фильтр `ratings.rendering` получает `target_type`, `target_key`, `average`,
`count`, `own`, `scale` и готовый `html`. Обработчик может вернуть изменённый
HTML, не вмешиваясь в подсчёт.