# Справочник типов полей

← [К разделу «Поля документов»](README.md)

AVE.cms показывает все зарегистрированные типы в разделе **Рубрики и поля →
Типы полей**. Там тип можно включить или скрыть из конструктора новых рубрик.
Отключение не удаляет обработчик и не ломает уже созданные поля.

## Рекомендуемые типы

Эти типы предназначены для новых рубрик. Они объединяют несколько узких legacy-
типов, хранят настройки в JSON и имеют предсказуемые форматы для API, фильтров и
публичных шаблонов.

| Код | Что делает | Чем отличается от старых типов |
| --- | --- | --- |
| `content` | Обычный текст, Tiptap или CodeMirror в зависимости от настройки режима. | Заменяет отдельный выбор между `multi_line`, `richtext` и `code`; режим можно настроить без смены типа поля. |
| `number` | Число, сумма, процент, величина или рейтинг; поддерживает единицу, точность и числовой индекс. | Заменяет `single_line_numeric*`; хранит одно каноническое число, а формат относится к настройкам. |
| `date_time` | Дата либо дата со временем с настраиваемым публичным форматом. | Один контракт вместо разрозненных вариантов `date`; хранит Unix timestamp. |
| `period` | Начало и окончание события или другого временного периода. | Две связанные даты хранятся одним структурированным значением. |
| `choice` | Одиночный или множественный выбор со стабильными ключами и подписями. | Заменяет `drop_down`, `drop_down_key`, `multi_select` и флажки; подпись можно менять без изменения сохранённого ключа. |
| `contact` | Email, телефон или URL с режимной проверкой и безопасной публичной ссылкой. | Валидация и способ вывода являются частью типа, а не шаблона сайта. |
| `color` | HEX-цвет с визуальным выбором и ручным вводом. | Нормализует значение и не требует обычного текстового поля с собственной проверкой. |
| `range` | Нижняя и верхняя граница с единицей измерения. | Границы хранятся вместе в JSON и доступны как единое значение. |
| `dimensions` | Длина, ширина и высота с общей единицей измерения. | Не требует трёх отдельных полей или строки с разделителями. |
| `packages` | Сортируемый список грузовых мест: габариты и вес каждой упаковки. | Поддерживает любое количество коробок и хранит их структурированно. |
| `address` | Структурированный адрес с необязательными координатами. | Части адреса доступны отдельно, но принадлежат одному полю. |

Метка **Новый** в панели означает рекомендуемый нативный контракт, а не то, что
тип экспериментальный. Для нового проекта сначала включайте только нужные типы
из этой таблицы.

## Текст и простые значения

Следующие типы сохранены для совместимости с существующими рубриками и данными.

| Код | Назначение |
| --- | --- |
| `single_line` | Короткая строка. Для новых полей используйте `content` в режиме обычного текста. |
| `single_line_numeric` | Одно legacy-число. Для новых полей используйте `number`. |
| `single_line_numeric_two` | Две числовые части, разделённые `|`. Предпочтительнее подходящий структурный тип. |
| `single_line_numeric_three` | Три числовые части, разделённые `|`; для габаритов используйте `dimensions`. |
| `multi_line` | Полноразмерный legacy rich text. Для новых полей используйте `content`. |
| `multi_line_simple` | Rich text средней высоты. Высота теперь является настройкой `content`. |
| `multi_line_slim` | Компактный rich text. Высота теперь является настройкой `content`. |
| `richtext` | Форматированный HTML. Для новых полей используйте `content` в режиме Tiptap. |
| `code` | Исходный код с CodeMirror. Для новых полей используйте `content` в режиме кода. |
| `checkbox` | Одно булево значение. Используется, когда нужен отдельный переключатель. |
| `date` | Legacy-дата или дата-время. Для новых полей используйте `date_time`. |
| `link` | URL или относительная ссылка без режимов `contact`. |

## Списки и варианты

| Код | Назначение |
| --- | --- |
| `drop_down` | Один вариант из списка legacy-значений. |
| `drop_down_key` | Один вариант, где отдельно хранятся ключ и видимая подпись. |
| `multi_select` | Несколько значений из заданного набора. |
| `checkbox_multi` | Несколько вариантов, показанных флажками. |
| `multi_checkbox` | Множественный legacy-выбор с JSON/serialize-совместимостью. |
| `multi_list` | Повторяемые пары параметр/значение. |
| `multi_list_single` | Повторяемый одноколоночный список. |
| `multi_list_triple` | Повторяемый список из трёх частей. |
| `multi_links` | Повторяемые ссылки с подписями. |

Новый `choice` предпочтительнее старых вариантов выбора: он хранит стабильный
ключ отдельно от подписи и одинаково работает в одиночном и множественном
режимах. Повторяемые произвольные записи при этом остаются задачей типов
`multi_list*`, а не `choice`.

## Медиа и файлы

| Код | Значение документа | Назначение |
| --- | --- | --- |
| `image_single` | `url`, `description` | Одно изображение: загрузка или выбор из медиабраузера. |
| `image_multi` | Список `url`, `description` | Обычная сортируемая галерея. |
| `image_mega` | Список `url`, `title`, `description`, `link` | Расширенная галерея с метаданными и ссылкой для каждого изображения. |
| `download` | `url`, `title` | Один файл для скачивания. |
| `doc_files` | Список `name`, `description`, `url` | Несколько файлов документа. |
| `youtube` | URL/ID и параметры ролика | Встраиваемое видео YouTube. |
| `text_to_image` | Текст | Legacy-тип, превращающий текст в изображение при выводе. |

Медиа-типы читают старые строки и PHP `serialize`, но при новом сохранении
записывают JSON. Публичные шаблоны получают одинаковую структуру независимо от
того, в каком историческом формате лежит значение.

У каждого типа `image_single`, `image_multi`, `image_mega`, `download` и
`doc_files` есть настройка **Папка файлов документа**. Она определяет конечный
путь новых загрузок и поддерживает `%id`, `%rubric_id`, `%rubric_alias`,
`%field_id`, `%field_alias`, `%Y`, `%m`, `%d`. Пока ID нового документа неизвестен, файл
хранится в закрытом черновике и переносится транзакционно после сохранения.
Подробности приведены в разделе [Медиа и миниатюры](../media/README.md#файлы-нового-документа).

## Связи документов

| Код | Назначение |
| --- | --- |
| `tags` | Набор тегов поля документа. Не путать с системными тегами документа. |
| `doc_from_rub` | Выбор одного документа из одной или нескольких рубрик. |
| `doc_from_rub_all` | Автоматическая работа со всеми документами выбранной рубрики; сохранён для legacy-сценариев. |
| `doc_from_rub_check` | Ручной множественный выбор связанных документов. |
| `doc_from_rub_search` | Множественный выбор документов через поиск. |
| `analoque` | Упорядоченные аналоги или документы, продаваемые вместе. |
| `teasers` | Упорядоченный список документов для вывода тизерами. |
| `catalog` | Привязка документа к разделам конструктора каталога. |

## Как переходить со старого типа

Не меняйте `rubric_field_type` напрямую в БД. Даже похожие поля могут отличаться
форматом значения, индексом и публичным шаблоном.

| Было | Обычно использовать для нового поля |
| --- | --- |
| `multi_line`, `multi_line_simple`, `multi_line_slim`, `richtext`, `code` | `content` с нужным режимом и высотой редактора |
| `single_line_numeric` | `number` |
| `single_line_numeric_three` для габаритов | `dimensions` |
| Набор отдельных полей коробки | `packages` |
| `drop_down`, `drop_down_key`, `multi_select`, `checkbox_multi`, `multi_checkbox` | `choice` |
| Два отдельных поля начала и окончания | `period` |
| Обычная строка для email, телефона или URL | `contact` |

Существующие legacy-поля не требуется мигрировать только ради нового редактора:
они являются полноценными зарегистрированными типами. Миграция нужна, когда
требуются новый структурированный формат, единый API-контракт или упрощение
набора полей рубрики.