- Пользовательский шаблон заменяет отображение существующего блока вашей собственной разметкой и передаёт вам данные этого блока (заголовок и счётчик товаров у Header, итоги у Summary и так далее). Он не добавляет ничего нового; он переоформляет один блок.
- Блок Custom code добавляет новый блок произвольного HTML или React в любое место корзины.
- Выберите блок в редакторе и откройте его вкладку Code.
- Отредактируйте шаблон по умолчанию. Пользовательские шаблоны — это только JSX (выбор HTML-или-JSX есть только у блока Custom code).
- Нажмите Compile. Компиляция удаляет типы и транспилирует JSX, поэтому она ловит синтаксические ошибки. Ошибки типов компиляцию не останавливают — редактор подсвечивает их по мере ввода тем же IntelliSense, который автодополняет пропсы блока.
- Включите шаблон, чтобы корзина использовала его вместо встроенного отображения. Когда шаблон включён, рядом с блоком в боковой панели появляется зелёный значок </>, а на вкладке Code — пульсирующая зелёная точка. Оба индикатора исчезают, если выключить шаблон.
- Reset to default в любой момент восстанавливает исходный шаблон блока.
- Правила компиляции (одно выражение, без
export default, без импортов) - Точные пропсы, которые получает блок, совпадающие с тем, что показывает IntelliSense редактора
- Заблокированную сигнатуру функции, которую требует редактор
- Специфичные для блока правила (денежные форматы, какие обработчики подключать, требования доступности)
- Раздел для заполнения, куда вы вставляете свой текущий шаблон и описываете желаемое изменение
Промпт специфичен для каждого блока. Кнопка Copy AI prompt появляется только на блоках, поддерживающих пользовательские шаблоны.
Что вы сохраняете: позицию блока в корзине, его переключатель видимости, его настройки (которые по-прежнему питают получаемые вами пропсы), панель пользовательского CSS корзины и встроенный скелетон загрузки.
Последнее удивляет людей. Блок проверяет, загружается ли ещё корзина, до обращения к вашему шаблону, поэтому встроенный скелетон отображается во время загрузки, а ваш шаблон выполняется только после готовности корзины. Вам не нужно создавать состояние загрузки.
Ваш шаблон — это один функциональный компонент. Он компилируется из TSX, поэтому аннотации типов допустимы и удаляются при компиляции. Именно поэтому шаблоны по умолчанию написаны с ними:
- Вам доступны пять хуков:
useState,useEffect,useMemo,useRefиuseCallback. ПлюсFragmentдля<>…</>. - Импортов нет. Вы не можете ничего
import, и в области видимости нет объектаReact, поэтому никакихReact.useReducer,React.Children. Если хука нет в списке выше, он недоступен. - Пропсы доступны только для чтения. Мутирование пропа не даст ничего полезного. Чтобы изменить корзину, используйте пропсы-обработчики, которые даёт блок (
onClose,increment,selectPlanи так далее), а не запись в пропсы напрямую. windowдоступен, поэтому шаблон может обращаться к Cart SDK черезwindow.aftersell.cart, когда нужно что-то, чего пропсы блока не покрывают.
- Пропсы
*Html— это предварительно очищенный форматированный текст. Отображайте их черезdangerouslySetInnerHTML. Они уже прошли через санитайзер корзины, а токены мерчанта вроде{{total_price}}уже подставлены. - Цены, приходящие как
string, уже отформатированы в денежном формате магазина. Цены какnumber— в центах. Блок даёт вам либо одно, либо другое, и таблица каждого блока указывает, что именно. isLoadingвнутри шаблона всегдаfalse. Блок отображает встроенный скелетон и вызывает ваш шаблон только после загрузки корзины, поэтому проп передаётся для полноты, а не для ветвления.
Несколько блоков в определённых состояниях вообще ничего не возвращают, поэтому ваш шаблон никогда не вызывается с пустыми данными. Шаблон Rewards никогда не видит пустой
milestones, а шаблон Subscription upgrade никогда не видит view равный null. Справочник каждого блока отмечает, где это применяется, чтобы вы могли пропустить ветку пустого состояния.
Итак,
cart-internal-header__title — это то, что делает заголовок похожим на встроенный, а cart-external-header__title — рукоятка, за которую нужно браться, когда вы хотите изменить его вид.
Если вы переставляете элементы, переименовываете или добавляете что-то внутри существующей структуры, оставьте имена классов в покое. Вы бесплатно сохраняете встроенный вид, а переоформляете через пользовательский CSS, нацеливаясь на хуки cart-external-*.
Как только вы меняете структуру DOM, а не подправляете её, уберите оба семейства из вашей разметки и используйте собственные имена классов. Для каждого есть своя причина.
Уберите cart-internal-*, потому что встроенный CSS написан для встроенного DOM. Оставите эти классы на перестроенной разметке — и унаследуете правила макета, предполагающие элементы, которых у вас больше нет: flex-контейнеры, ожидающие других детей, интервалы между переместившимися элементами, позиционирование относительно того, что вы удалили. Обычно это проявляется как ваш CSS, который «не работает», когда на самом деле побеждают встроенные правила.
Два способа оформить то, что вы построили:
Лучше всего для всего, что вы будете поддерживать или переиспользовать. Дайте своим классам префикс, с которым никто не столкнётся, обычно имя вашего магазина или бренда:
.header или .title рискует конфликтовать с собственными классами корзины, шаблоном другого приложения или будущим блоком.
Без похода в панель CSS, и всё живёт в одном месте:
:hover и других псевдоклассов, нет медиазапросов и нет переиспользования между блоками. Переходите к варианту 1, когда понадобится что-то из этого.
Корзина отображается в shadow root, поэтому таблица стилей вашей темы не может проникнуть внутрь. Стили для пользовательского шаблона должны идти из собственной панели Custom CSS корзины или из инлайн-стилей, а не из вашей темы. См. Пользовательский CSS.
Поскольку блок молча исчезает, а не выдаёт видимую ошибку, всегда проверяйте шаблон в предпросмотре перед публикацией. Если блок пропал, сначала откройте консоль браузера.
Две вещи, от которых стоит защищаться, поскольку обе роняют шаблон, предполагающий обратное:
- Пропсы, допускающие null. Многие пропсы равны
nullв нормальных условиях (logoUrlбез логотипа,imageUrlбез изображения,variantTitleу товара с одним вариантом). Проверяйте перед использованием. - Массивы, которые могут быть пустыми.
discountTagsиdiscountCodesгораздо чаще равны[], чем нет.
- Пользовательские шаблоны — это переопределения отображения. Чтобы выполнять логику для корзины (подписываться на события, добавлять товары, реагировать на изменения), используйте пользовательские скрипты и Cart SDK.
- Почти каждый блок его поддерживает. Исключения — блок Express payments, который содержит собственные платёжные кнопки Shopify, и сам контейнер Cart items, хотя строка Product внутри него пользовательский шаблон поддерживает.
- Шаблон не может изменить то, что блок делает по существу. Он меняет то, как представлены данные блока, а не сами данные или поведение за ними.
Блок Custom code — единственная поверхность, которая добавляет разметку, а не заменяет отображение блока, поэтому его пропсы другие: вся корзина плюс действие добавления в корзину. См. Блоки пользовательского кода → Пропсы.