Skip to main content
Szablon niestandardowy pozwala nadpisać sposób renderowania pojedynczego bloku. Zamiast wbudowanego interfejsu bloku koszyk renderuje twój własny JSX, korzystając z tych samych danych, których blok normalnie by użył. To zdolność przekrojowa, a nie osobny blok: większość bloków udostępnia ją z karty Code. Ta strona opisuje to, co dotyczy każdego bloku. Po propsy, które przekazuje ci konkretny blok, przejdź do dokumentacji danego bloku.

​
Szablon niestandardowy vs blok Custom code

Brzmią podobnie, ale robią różne rzeczy:
  • Szablon niestandardowy zastępuje renderowanie istniejącego bloku twoją własną strukturą i przekazuje ci dane tego bloku (tytuł i liczbę pozycji z Headera, sumy z Summary itd.). Nie dodaje niczego nowego; przestylizowuje jeden blok.
  • Blok Custom code dodaje nowy blok dowolnego HTML lub Reacta w dowolnym miejscu koszyka.
Sięgnij po szablon niestandardowy, gdy wbudowany blok jest prawie dobry, ale potrzebujesz innego układu lub struktury. Sięgnij po blok Custom code, gdy chcesz dodać coś, czego wbudowane bloki nie pokrywają.

​
Korzystanie z szablonu niestandardowego

  1. Zaznacz blok w edytorze i otwórz jego kartę Code.
  2. Edytuj domyślny szablon. Szablony niestandardowe to wyłącznie JSX (wybór HTML-albo-JSX jest zarezerwowany dla bloku Custom code).
  3. Kliknij Compile. Kompilacja usuwa typy i transpiluje JSX, więc wychwytuje błędy składni. Błędy typów nie zatrzymują kompilacji — edytor oznacza je w trakcie pisania, z tym samym IntelliSense, które autouzupełnia propsy bloku.
  4. Włącz szablon, aby koszyk używał go zamiast wbudowanego renderowania.
  5. Reset to default przywraca oryginalny szablon bloku w dowolnym momencie.

​
Pisanie szablonu z pomocą AI

Karta Code zawiera przycisk Copy AI prompt (ikona różdżki ✦). Kliknięcie kopiuje do schowka samodzielny brief, który możesz wkleić bezpośrednio do sesji czatu AI (Claude, ChatGPT lub podobne). Prompt zawiera wszystko, czego AI potrzebuje, aby napisać prawidłowy szablon dla tego konkretnego bloku:
  • Zasady kompilacji (pojedyncze wyrażenie, brak export default, brak importów)
  • Dokładne propsy, które otrzymuje blok, zgodne z tym, co pokazuje IntelliSense edytora
  • Zablokowaną sygnaturę funkcji wymuszaną przez edytor
  • Zasady specyficzne dla bloku (formaty pieniężne, które handlery podłączyć, wymagania dostępności)
  • Sekcję do uzupełnienia, w którą wklejasz swój bieżący szablon i opisujesz zmianę, jakiej chcesz
Po skopiowaniu otwórz sesję AI, wklej prompt, uzupełnij dwa puste miejsca na dole (twój bieżący szablon i pożądaną zmianę) i wyślij. AI zwraca kompletny szablon, który możesz wkleić z powrotem do edytora i skompilować.
Wklej swój istniejący szablon w sekcję do uzupełnienia, zamiast zostawiać ją pustą. AI używa go jako punktu wyjścia, więc każda dokonana już personalizacja zostaje przeniesiona, a nie zastąpiona domyślnym szablonem.
Prompt jest specyficzny dla każdego bloku. Przycisk Copy AI prompt pojawia się tylko na blokach obsługujących szablony niestandardowe.
Domyślny szablon, od którego zaczynasz, to działająca kopia wbudowanej struktury bloku, więc zawsze masz poprawny, renderujący się punkt odniesienia do modyfikacji zamiast pustej strony. Sięgaj po Reset to default, gdy chcesz odzyskać ten punkt odniesienia.Nie zawsze jest to zgodność co do bajta. Domyślny szablon Headera renderuje też logoUrl, dla którego wbudowana struktura nie ma miejsca, więc włączenie tego szablonu to sposób, w jaki przesłany obraz nagłówka pojawia się po raz pierwszy.

​
Co zastępuje twój szablon

Szablon zastępuje renderowanie bloku całkowicie. Wokół twojego JSX nie pozostaje żaden wrapper, co ma konsekwencje warte poznania, zanim zaczniesz coś usuwać:
Karta Design to pułapka, w którą wpadają ludzie. Gdy szablon niestandardowy jest aktywny, pola karty Design są wyłączone, a obok nagłówka „Design” pojawia się ikona ostrzeżenia. Najedź na ikonę, aby zobaczyć powód. Stylizuj blok z poziomu szablonu, inline albo własnym CSS. Pola włączają się ponownie, gdy tylko wyłączysz szablon niestandardowy.
Co zachowujesz: pozycję bloku w koszyku, jego przełącznik widoczności, jego ustawienia (które nadal zasilają otrzymywane propsy), panel Custom CSS koszyka oraz wbudowany szkielet ładowania. To ostatnie zaskakuje ludzi. Blok sprawdza, czy koszyk wciąż się ładuje, zanim dotrze do twojego szablonu, więc wbudowany szkielet renderuje się podczas ładowania, a twój szablon uruchamia się dopiero, gdy koszyk jest gotowy. Nie musisz budować stanu ładowania.

​
Co jest dostępne wewnątrz szablonu

Twój szablon to pojedynczy komponent funkcyjny. Kompiluje się z TSX, więc adnotacje typów są dozwolone i usuwane w czasie kompilacji. Dlatego domyślne szablony są z nimi napisane:
Linia sygnatury i zamykająca klamra są zablokowane — edytor nie pozwoli edytować żadnej z nich, a najechanie pokazuje „Locked — this line can’t be edited.” Piszesz treść między nimi. Reset to default to jedyna rzecz, która może je zastąpić. Co jeszcze ma znaczenie:
  • Dostajesz pięć hooków: useState, useEffect, useMemo, useRef i useCallback. Plus Fragment, dla <>…</>.
  • Nie ma importów. Nie możesz niczego importować i nie ma obiektu React w zakresie, więc żadnego React.useReducer, żadnego React.Children. Jeśli hooka nie ma na powyższej liście, nie jest dostępny.
  • Propsy są tylko do odczytu. Mutowanie propa nic użytecznego nie da. Aby zmienić koszyk, użyj propów-handlerów, które daje ci blok (onClose, increment, selectPlan itd.), zamiast pisać bezpośrednio do propsów.
  • window jest osiągalne, więc szablon może wywołać Cart SDK przez window.aftersell.cart, gdy potrzebuje czegoś, czego propsy bloku nie pokrywają.

​
Konwencje wspólne dla wszystkich bloków

Trzy zasady obowiązują wszędzie, a ich znajomość usuwa większość zgadywania:
  • Propsy *Html to wstępnie oczyszczony rich text. Renderuj je przez dangerouslySetInnerHTML. Przeszły już przez sanitizer koszyka, a tokeny sprzedawcy jak {{total_price}} są już rozwiązane.
  • Ceny przychodzące jako string są już sformatowane w formacie walutowym sklepu. Ceny jako number są w centach. Blok daje ci jedno albo drugie, a tabela każdego bloku mówi które.
  • isLoading jest zawsze false wewnątrz szablonu. Blok renderuje swój wbudowany szkielet i wywołuje twój szablon dopiero po załadowaniu koszyka, więc prop jest przekazywany dla kompletności, a nie po to, żebyś na nim rozgałęział logikę.
Kilka bloków w pewnych stanach nie zwraca w ogóle niczego, więc twój szablon nigdy nie jest wywoływany z pustymi danymi. Szablon Rewards nigdy nie widzi pustych milestones, a szablon Subscription upgrade nigdy nie widzi view równego null. Dokumentacja każdego bloku odnotowuje, gdzie to obowiązuje, więc możesz pominąć gałąź stanu pustego.

​
Stylizowanie szablonu niestandardowego

Domyślny szablon, od którego zaczynasz, niesie nazwy klas bloku. Sposób stylizowania twoich zmian zależy od tego, jak daleko odchodzisz od tego punktu wyjścia.

​
Dwie rodziny klas

Każdy element w domyślnym szablonie niesie sparowaną nazwę klasy, a pełnią one bardzo różne role: Zatem cart-internal-header__title sprawia, że tytuł wygląda jak wbudowany tytuł, a cart-external-header__title to uchwyt, za który masz chwycić, gdy chcesz zmienić jego wygląd.

​
Małe zmiany: zachowaj obie nazwy klas

Jeśli przestawiasz elementy, zmieniasz etykiety lub dodajesz coś wewnątrz istniejącej struktury, zostaw nazwy klas w spokoju. Zachowujesz wbudowany wygląd za darmo, a przestylizowujesz przez Custom CSS celujący w zaczepy cart-external-*.

​
Restrukturyzacja: porzuć obie nazwy klas

Gdy zmieniasz strukturę DOM, a nie ją poprawiasz, zdejmij obie rodziny ze swojej struktury i użyj własnych nazw klas. Dla każdej jest osobny powód. Porzuć cart-internal-*, ponieważ wbudowany CSS był pisany dla wbudowanego DOM. Zachowaj te klasy na zrestrukturyzowanej strukturze, a odziedziczysz reguły układu zakładające elementy, których już nie masz: kontenery flex oczekujące innych dzieci, odstępy między elementami, które się przesunęły, pozycjonowanie względem czegoś, co usunąłeś. Zwykle objawia się to tym, że twój własny CSS „nie działa”, bo wygrywają reguły wbudowane.
Porzuć cart-external-*, ponieważ to nazwa współdzielona, nie twoja. Te nazwy klas znaczą coś konkretnego na wbudowanej strukturze, a twój Custom CSS jest pisany raz dla całego koszyka. Jeśli zrestrukturyzowany szablon je ponownie użyje, każda napisana reguła celuje zarówno w twoją strukturę, jak i wbudowaną.To psuje się w momencie wyłączenia szablonu niestandardowego: blok wraca do wbudowanej struktury, a twój CSS nadal w nią celuje, stylizując teraz DOM, dla którego nigdy nie był pisany. Twój własny prefiks utrzymuje oba czysto rozdzielone, więc wyłączenie szablonu jest czystym powrotem.
Dwa sposoby na stylizację tego, co zbudujesz:

​
Opcja 1: własne nazwy klas plus Custom CSS

Najlepsza do wszystkiego, co będziesz utrzymywać lub ponownie wykorzystywać. Nadaj swoim klasom prefiks, z którym nikt inny nie będzie kolidować — zwykle nazwę sklepu lub marki:
Następnie w edytorze koszyka wybierz Cart settings w lewym panelu i otwórz kartę Custom CSS po prawej:
Prefiks ma większe znaczenie, niż się wydaje. Bez niego klasa jak .header czy .title ryzykuje kolizję z własnymi klasami koszyka, szablonem innej aplikacji lub przyszłym blokiem.

​
Opcja 2: style inline

Bez wycieczki do panelu CSS, a wszystko żyje w jednym miejscu:
Dobre dla rusztowania układu i jednorazowych zmian. Jego ograniczenia to te typowe: brak :hover i innych pseudoklas, brak media queries i brak ponownego użycia między blokami. Sięgnij po opcję 1, gdy potrzebujesz któregokolwiek z nich.

​
Wybór podejścia

Koszyk renderuje się w shadow root, więc arkusz stylów twojego motywu nie sięga do jego wnętrza. Style dla szablonu niestandardowego muszą pochodzić z własnego panelu Custom CSS koszyka lub ze stylów inline, nie z motywu. Zobacz Niestandardowy CSS.

​
Gdy szablon zawodzi

Zepsuty szablon nigdy nie psuje koszyka. Blok renderuje nic, a wszystko wokół niego działa dalej — co jest bezpieczne, ale łatwe do przeoczenia: objawem jest puste miejsce tam, gdzie powinien być twój blok. Ponieważ blok po cichu znika, zamiast widocznie zgłaszać błąd, zawsze sprawdzaj szablon w podglądzie przed publikacją. Jeśli blok zniknął, najpierw otwórz konsolę przeglądarki. Dwie rzeczy warte zabezpieczenia, bo obie zawieszają szablon, który zakłada inaczej:
  • Propsy dopuszczające null. Wiele propsów jest null w normalnych warunkach (logoUrl bez logo, imageUrl bez obrazu, variantTitle na produkcie z jednym wariantem). Sprawdzaj przed użyciem.
  • Tablice, które mogą być puste. discountTags i discountCodes są [] znacznie częściej niż nie.

​
Ograniczenia

  • Szablony niestandardowe to nadpisania wyświetlania. Aby uruchamiać logikę na koszyku (subskrybować zdarzenia, dodawać pozycje, reagować na zmiany), użyj Niestandardowych skryptów i Cart SDK.
  • Obsługuje je prawie każdy blok. Wyjątkami są blok Express payments, który hostuje własne przyciski płatności Shopify, oraz sam kontener Cart items, choć wiersz Product wewnątrz niego szablon niestandardowy obsługuje.
  • Szablon nie może zmienić tego, co blok fundamentalnie robi. Zmienia sposób prezentacji danych bloku, a nie dane czy zachowanie za nimi.

​
Propsy każdego bloku

Każdy blok przekazuje własne dane. Pełna tabela propsów, z typami i przykładem, znajduje się na stronie danego bloku: Blok Custom code to jedyna powierzchnia, która dodaje strukturę zamiast zastępować renderowanie bloku, więc jego propsy są inne: cały koszyk plus akcja dodania do koszyka. Zobacz Bloki Custom code → Propsy.