Skip to main content
Um template personalizado permite substituir a forma como um bloco individual é renderizado. Em vez da interface nativa do bloco, o carrinho renderiza seu próprio JSX, usando os mesmos dados que o bloco normalmente usaria. É uma capacidade transversal, e não um bloco por si só: a maioria dos blocos a expõe pela sua aba Code. Esta página cobre o que se aplica a todos os blocos. Para as props que um bloco específico entrega a você, vá para a referência do próprio bloco.

​
Template personalizado vs. bloco Custom code

Eles soam parecidos, mas fazem coisas diferentes:
  • Um template personalizado substitui a renderização de um bloco existente pela sua própria marcação e entrega a você os dados daquele bloco (o título e a contagem de itens do Header, os totais do Summary e assim por diante). Ele não adiciona nada novo; ele reestiliza um bloco.
  • O bloco Custom code adiciona um novo bloco de HTML ou React arbitrário em qualquer lugar do carrinho.
Recorra a um template personalizado quando o bloco nativo está quase certo, mas você precisa de um layout ou marcação diferente. Recorra a um bloco Custom code quando quiser adicionar algo que os blocos nativos não cobrem.

​
Usando um template personalizado

  1. Selecione um bloco no editor e abra sua aba Code.
  2. Edite o template padrão. Templates personalizados são somente JSX (a escolha entre HTML ou JSX é exclusiva do bloco Custom code).
  3. Clique em Compile. Compilar remove os tipos e transpila o JSX, então captura erros de sintaxe. Erros de tipo não impedem a compilação — o editor os marca inline conforme você digita, com o mesmo IntelliSense que faz autocompletar das props do bloco.
  4. Ative o template para que o carrinho o use em vez da renderização nativa.
  5. Reset to default restaura o template original do bloco a qualquer momento.

​
Escrevendo um template com IA

A aba Code inclui um botão Copy AI prompt (ícone de varinha ✦). Clicar nele copia para a sua área de transferência um briefing autocontido que você pode colar diretamente em uma sessão de chat de IA (Claude, ChatGPT ou similar). O prompt inclui tudo o que a IA precisa para escrever um template válido para aquele bloco específico:
  • As regras de compilação (expressão única, sem export default, sem imports)
  • As props exatas que o bloco recebe, correspondendo ao que o IntelliSense do editor mostra
  • A assinatura de função travada que o editor impõe
  • Regras específicas do bloco (formatos de dinheiro, quais handlers conectar, requisitos de acessibilidade)
  • Uma seção para preencher, onde você cola seu template atual e descreve a mudança que quer
Depois de copiar, abra uma sessão de IA, cole o prompt, preencha os dois espaços em branco no final (seu template atual e a mudança que você quer) e envie. A IA retorna um template completo que você pode colar de volta no editor e compilar.
Cole seu template existente na seção de preenchimento em vez de deixá-la em branco. A IA o usa como ponto de partida, então qualquer personalização que você já fez é levada adiante em vez de ser substituída pelo padrão.
O prompt é específico de cada bloco. O botão Copy AI prompt só aparece em blocos que suportam templates personalizados.
O template padrão do qual você parte é uma cópia funcional da marcação nativa do bloco, então você sempre tem uma referência correta e renderizável para modificar, em vez de uma página em branco. Recorra a Reset to default sempre que quiser essa referência de volta.Nem sempre é uma correspondência byte a byte. O template padrão do Header também renderiza logoUrl, para o qual a marcação nativa não tem posicionamento, então ativar esse template é a forma como uma imagem de cabeçalho enviada aparece pela primeira vez.

​
O que seu template substitui

Um template substitui a renderização do bloco por completo. Não sobra nenhum wrapper ao redor do seu JSX, o que tem consequências que vale conhecer antes de começar a apagar coisas:
A aba Design é a que pega as pessoas de surpresa. Enquanto um template personalizado está ativo, os campos da aba Design ficam desativados e um ícone de aviso aparece ao lado do título “Design”. Passe o mouse sobre o ícone para ver o motivo. Estilize o bloco a partir do seu template, seja inline ou com seu próprio CSS. Os campos são reativados assim que você desativa o template personalizado.
O que você mantém: a posição do bloco no carrinho, seu botão de visibilidade, suas configurações (que continuam alimentando as props que você recebe), o painel de Custom CSS do carrinho e o skeleton de carregamento nativo. Esse último surpreende as pessoas. O bloco verifica se o carrinho ainda está carregando antes de chegar ao seu template, então o skeleton nativo é renderizado durante o carregamento e seu template só executa quando o carrinho está pronto. Você não precisa construir um estado de carregamento.

​
O que está disponível dentro de um template

Seu template é um único componente de função. Ele compila a partir de TSX, então anotações de tipo são permitidas e removidas na compilação. É por isso que os templates padrão são escritos com elas:
A linha da assinatura e a chave de fechamento são travadas — o editor não deixa você editar nenhuma delas, e ao passar o mouse aparece “Locked — this line can’t be edited.” Você escreve o corpo entre elas. Reset to default é a única coisa que pode substituí-las. O que mais importa:
  • Você tem cinco hooks: useState, useEffect, useMemo, useRef e useCallback. Mais Fragment, para <>…</>.
  • Não há imports. Você não pode fazer import de nada, e não há objeto React no escopo, então nada de React.useReducer nem React.Children. Se um hook não está na lista acima, ele não está disponível.
  • As props são somente leitura. Mutar uma prop não vai fazer nada útil. Para alterar o carrinho, use as props de handler que o bloco fornece (onClose, increment, selectPlan e assim por diante) em vez de escrever nas props diretamente.
  • window é alcançável, então um template pode chamar o Cart SDK via window.aftersell.cart quando precisa de algo que as props do bloco não cobrem.

​
Convenções em todos os blocos

Três regras valem em todo lugar, e conhecê-las elimina a maior parte das adivinhações:
  • Props *Html são rich text pré-sanitizado. Renderize-as com dangerouslySetInnerHTML. Elas já passaram pelo sanitizador do carrinho, e tokens do lojista como {{total_price}} já estão resolvidos.
  • Preços que chegam como string já estão formatados no formato de dinheiro da loja. Preços como number estão em centavos. Um bloco fornece um ou outro, e a tabela de cada bloco diz qual.
  • isLoading é sempre false dentro de um template. O bloco renderiza seu skeleton nativo e só chama seu template quando o carrinho carregou, então a prop é passada por completude, não para você ramificar sobre ela.
Alguns blocos não retornam nada em certos estados, então seu template nunca é chamado com dados vazios. O template do Rewards nunca vê um milestones vazio, e o template do Subscription upgrade nunca vê um view nulo. A referência de cada bloco indica onde isso se aplica, para que você possa pular a ramificação de estado vazio.

​
Estilizando um template personalizado

O template padrão do qual você parte carrega os nomes de classe do bloco. Como você estiliza suas edições depende de quão longe você vai desse ponto de partida.

​
As duas famílias de classes

Todo elemento em um template padrão carrega um nome de classe pareado, e eles fazem trabalhos muito diferentes: Então cart-internal-header__title é o que faz o título parecer com o título nativo, e cart-external-header__title é a alça que você deve agarrar quando quer mudar sua aparência.

​
Mudanças pequenas: mantenha os dois nomes de classe

Se você está reordenando elementos, mudando rótulos ou adicionando algo dentro da estrutura existente, deixe os nomes de classe em paz. Você mantém o visual nativo de graça e reestiliza pelo Custom CSS mirando os ganchos cart-external-*.

​
Reestruturação: descarte os dois nomes de classe

Quando você está mudando a estrutura DOM em vez de ajustá-la, retire ambas as famílias da sua marcação e use seus próprios nomes de classe em vez disso. Há um motivo distinto para cada uma. Descarte cart-internal-* porque o CSS nativo foi escrito para o DOM nativo. Mantenha essas classes em uma marcação reestruturada e você herda regras de layout que pressupõem elementos que você não tem mais: contêineres flex esperando filhos diferentes, espaçamento entre elementos que se moveram, posicionamento relativo a algo que você removeu. Isso geralmente aparece como o seu próprio CSS “não funcionando” quando as regras nativas são as que estão vencendo.
Descarte cart-external-* porque é um nome compartilhado, não seu. Esses nomes de classe significam algo específico na marcação nativa, e seu Custom CSS é escrito uma única vez para o carrinho inteiro. Se um template reestruturado os reutiliza, qualquer regra que você escrever mira tanto a sua estrutura quanto a nativa.Isso dá errado no momento em que você desativa o template personalizado: o bloco reverte à marcação nativa, e seu CSS continua apontando para ela, agora estilizando um DOM para o qual nunca foi escrito. Um prefixo próprio mantém os dois claramente separados, para que desativar um template seja uma reversão limpa.
Duas formas de estilizar o que você construiu:

​
Opção 1: seus próprios nomes de classe mais Custom CSS

Melhor para qualquer coisa que você vai manter ou reutilizar. Dê às suas classes um prefixo com o qual ninguém mais vai colidir, geralmente o nome da sua loja ou marca:
Depois, no Cart Editor, selecione Cart settings no painel esquerdo e abra a aba Custom CSS à direita:
Um prefixo importa mais do que parece. Sem um, uma classe como .header ou .title corre o risco de colidir com as classes do próprio carrinho, com o template de outro app ou com um bloco futuro.

​
Opção 2: estilos inline

Sem ida e volta ao painel de CSS, e tudo fica em um único lugar:
Bom para estrutura de layout e casos pontuais. Seus limites são os habituais: sem :hover ou outras pseudoclasses, sem media queries e sem reutilização entre blocos. Recorra à Opção 1 quando quiser qualquer uma dessas coisas.

​
Escolhendo uma abordagem

O carrinho é renderizado em um shadow root, então a folha de estilos do seu tema não consegue alcançar seu interior. Os estilos de um template personalizado precisam vir do painel Custom CSS do próprio carrinho ou de estilos inline, não do seu tema. Veja CSS personalizado.

​
Quando um template falha

Um template quebrado nunca quebra o carrinho. O bloco renderiza nada e tudo ao redor continua funcionando, o que é seguro mas fácil de passar despercebido: um espaço em branco onde seu bloco deveria estar é o sintoma. Como o bloco desaparece silenciosamente em vez de mostrar um erro visível, sempre verifique um template na pré-visualização antes de publicar. Se um bloco sumiu, abra o console do navegador primeiro. Duas coisas que vale a pena proteger, já que ambas quebram um template que pressupõe o contrário:
  • Props anuláveis. Muitas props são null em condições normais (logoUrl sem logo, imageUrl sem imagem, variantTitle em um produto de variante única). Verifique antes de usá-las.
  • Arrays que podem estar vazios. discountTags e discountCodes são [] na maioria das vezes.

​
Limitações

  • Templates personalizados são substituições de exibição. Para executar lógica no carrinho (assinar eventos, adicionar itens, reagir a mudanças), use Scripts personalizados e o Cart SDK.
  • Quase todo bloco suporta um. As exceções são o bloco Express payments, que hospeda os botões de pagamento da própria Shopify, e o contêiner Cart items em si, embora a linha Product dentro dele suporte um template personalizado.
  • Um template não pode mudar o que um bloco fundamentalmente faz. Ele muda como os dados do bloco são apresentados, não os dados ou o comportamento por trás deles.

​
Props de cada bloco

Cada bloco passa seus próprios dados. A tabela completa de props, com tipos e um exemplo trabalhado, fica na página daquele bloco: O bloco Custom code é a única superfície que adiciona marcação em vez de substituir a renderização de um bloco, então suas props são diferentes: o carrinho inteiro, mais uma ação de adicionar ao carrinho. Veja Blocos Custom code → Props.