12 KiB
Справочник типов полей
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 |
Три числовые части, разделённые ` |
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 нового документа неизвестен, файл
хранится в закрытом черновике и переносится транзакционно после сохранения.
Подробности приведены в разделе Медиа и миниатюры.
Связи документов
| Код | Назначение |
|---|---|
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-контракт или упрощение набора полей рубрики.