Контент витрины

Всё, что продавец правит в Маркетинг → Контент витрины, витрина получает одним полем Shop API — storefrontContent. Сервер отдаёт только включённое и попавшее в окно показа. Что из этого и как выводить, решает витрина.

Вкладки админки и поля API

Вкладка в админке	Поле `storefrontContent`	Что внутри
Главная	`page(key: "home")`	Страница из блоков: какие, в каком порядке
Шапка	`announcement`, `menu(key: "header")`	Полоса объявлений над шапкой, мегаменю
Баннеры	`banners(placement)`	Картинки с подписями и ссылками по местам показа
Подборки	`shelves(placement)`	Карусели товаров коллекции
Меню	`menus`, `menu(key)`	Любые меню по ключу: подвал, «Инфо», популярные запросы
Тексты	`texts`	Короткие тексты по ключу
Оформление	`theme`	Токены дизайна: цвет акцента, шрифт, размеры

Свой цвет раздела каталога задаётся не здесь, а в карточке коллекции — поле Collection.customFields.storefrontColor (#rgb или #rrggbb, пусто — общий акцент).

Весь контент одним запросом

В SDK это StorefrontContentDocument:

query StorefrontContent {
  storefrontContent {
    banners { id placement position title subtitle ctaLabel link alt
      asset { preview width height focalPoint { x y } }
      mobileAsset { preview width height focalPoint { x y } } }
    shelves { id placement position title subtitle link limit
      collection { id slug name } }
    menus { key groups { title section links { label href badge } } }
    texts { key value }
    theme { key value }
    announcement { background color interval messages { text link } }
  }
}

Отдельные запросы SDK — StorefrontBannersDocument и StorefrontShelvesDocument по месту показа, StorefrontMenuDocument по ключу меню, StorefrontPageDocument для страницы из блоков.

Страница из блоков

query StorefrontPage($key: String!) {
  storefrontContent {
    page(key: $key) {
      key
      modules {
        id type title link placement limit captions aspect
        collection { id slug name }
        bar { start end link background color }
      }
    }
  }
}

Сервер отдаёт только включённые блоки в порядке, заданном продавцом. page равно null, если продавец страницу не собирал: витрина показывает свою раскладку по умолчанию.

`type`	Блок	Откуда данные
`collage`	Плитки фото или видео, под ними полоса-кнопка или подписи	Баннеры места `placement`
`products`	Карусель товаров	Коллекция `collection`, первые `limit` товаров
`tiles`	Карусель плиток с подписями	Баннеры места `placement`
`gallery`	Лента фото	Баннеры места `placement`

Поля коллажа:

aspect — пропорции плиток: photo (как у первой картинки места), 4:5, 1:1, 8:5, 16:9; null — автоматически по числу плиток.
captions — подписи под плитками из заголовков баннеров.
bar — полоса-кнопка во всю ширину под коллажем: текст слева и справа, ссылка, цвета.

Кадрируйте фото вокруг asset.focalPoint — эту точку продавец ставит в карточке картинки.

Баннеры и подборки

Баннеры и подборки привязаны к месту показа (placement) — строке вида home.hero. Мест платформа не задаёт: какие читать, решает витрина, а продавец выбирает место в форме баннера.

Порядок — по position, при равенстве — по порядку создания. SDK-помощник inPlacement(items, placement) отбирает одно место, не меняя порядка.
У баннера есть окно показа: до startsAt и после endsAt сервер его не отдаёт. Выключенный баннер и баннер без картинки тоже не приходят.
mobileAsset — картинка для узкого экрана; null — показывайте основную.
У подборки limit — сколько товаров показать (от 1 до 48, по умолчанию 12). collection равна null, если коллекцию удалили или скрыли — такую подборку не показывают.

Тексты и тема

texts и theme — пары «ключ → значение». Ключи придумывает витрина и сообщает продавцу, какие из них она читает.

import { entriesRecord, entryValue } from '@fluttrium/shop-sdk';

const tiers = entryValue(content.texts, 'wholesale.tiers'); // «10:5, 30:15»
const theme = entriesRecord(content.theme); // { 'color-accent': '#2563eb', … }

Значение токена темы сервер проверяет: в нём не может быть ; { } < > \, переводов строк, незакрытых кавычек и подключения внешних ресурсов (url(), image-set() и подобных).

Полоса объявлений

announcement — до 5 сообщений над шапкой, сменяющих друг друга каждые interval секунд (от 3 до 30, по умолчанию 5). У сообщения текст до 160 символов и необязательная ссылка; у полосы — цвета фона и текста. null — объявлений нет или они выключены.

Безопасность ссылок и цветов

Сервер принимает ссылки, начинающиеся только с /, https://, http://, mailto: или tel:, и цвета только #rgb/#rrggbb. Но вводит их продавец, а выводит витрина, поэтому проверяйте и на выводе:

import { safeColor, safeHref } from '@fluttrium/shop-sdk';

<a href={safeHref(banner.link) ?? '/'}>…</a>;
<div style={{ background: safeColor(announcement.background) ?? undefined }} />;

Пределы

Что	Предел
Меню	30, в меню 20 групп, в группе 50 ссылок
Ссылка	подпись до 100 символов, адрес до 500, пометка до 20
Тексты	200 ключей, значение до 2000 символов
Тема	100 токенов, значение до 200 символов
Ключ меню, текста, токена	`^[a-z0-9][a-z0-9._-]{0,49}$`
Место показа	`^[a-z0-9][a-z0-9._-]{0,63}$`
Баннер	заголовок до 200, подзаголовок до 500, кнопка до 100, alt до 300 символов
Страницы из блоков	10 страниц, 30 блоков на странице, заголовок блока до 100 символов
Значение настройки целиком	200 000 символов JSON

Кеш

Контент меняется редко, а нужен на каждой странице. Кешируйте ответ на сервере витрины и сбрасывайте по времени: продавец увидит свою правку на сайте, когда кеш истечёт.