- Una plantilla personalizada reemplaza el renderizado de un bloque existente con tu propio marcado, y te entrega los datos propios de ese bloque (el título y el conteo de artículos del Header, los totales del Summary, etcétera). No agrega nada nuevo; rediseña un bloque.
- El bloque Custom code agrega un bloque nuevo de HTML o React arbitrario en cualquier parte del carrito.
- Selecciona un bloque en el editor y abre su pestaña Code.
- Edita la plantilla predeterminada. Las plantillas personalizadas son solo JSX (la elección entre HTML o JSX es exclusiva del bloque Custom code).
- Haz clic en Compile. Compilar elimina los tipos y transpila el JSX, así que detecta errores de sintaxis. Los errores de tipos no detienen la compilación: el editor los marca inline mientras escribes, con el mismo IntelliSense que autocompleta las props del bloque.
- Activa la plantilla para que el carrito la use en lugar del renderizado integrado. Cuando la plantilla está activada, aparece un icono verde </> junto al bloque en la barra lateral y un punto verde parpadeante en la pestaña Code. Ambos desaparecen si desactivas la plantilla.
- Reset to default restaura la plantilla original del bloque en cualquier momento.
- Las reglas de compilación (expresión única, sin
export default, sin imports) - Las props exactas que recibe el bloque, coincidiendo con lo que muestra el IntelliSense del editor
- La firma de función bloqueada que el editor impone
- Reglas específicas del bloque (formatos de dinero, qué handlers conectar, requisitos de accesibilidad)
- Una sección para completar donde pegas tu plantilla actual y describes el cambio que quieres
El prompt es específico de cada bloque. El botón Copy AI prompt solo aparece en bloques que admiten plantillas personalizadas.
Lo que conservas: la posición del bloque en el carrito, su interruptor de visibilidad, sus configuraciones (que siguen alimentando las props que recibes), el panel de Custom CSS del carrito y el skeleton de carga integrado.
Esto último sorprende a la gente. El bloque verifica si el carrito sigue cargando antes de llegar a tu plantilla, así que el skeleton integrado se renderiza durante la carga y tu plantilla solo se ejecuta una vez que el carrito está listo. No tienes que construir un estado de carga.
Tu plantilla es un único componente de función. Se compila desde TSX, así que las anotaciones de tipo están permitidas y se eliminan en tiempo de compilación. Por eso las plantillas predeterminadas están escritas con ellas:
- Tienes cinco hooks:
useState,useEffect,useMemo,useRefyuseCallback. MásFragment, para<>…</>. - No hay imports. No puedes hacer
importde nada, y no hay un objetoReacten alcance, así que no hayReact.useReducerniReact.Children. Si un hook no está en la lista de arriba, no está disponible. - Las props son de solo lectura. Mutar una prop no servirá de nada. Para cambiar el carrito, usa las props de handler que el bloque te da (
onClose,increment,selectPlan, etcétera) en lugar de escribir directamente en las props. windowes alcanzable, así que una plantilla puede llamar al Cart SDK víawindow.aftersell.cartcuando necesita algo que las props del bloque no cubren.
- Las props
*Htmlson texto enriquecido pre-sanitizado. Renderízalas condangerouslySetInnerHTML. Ya pasaron por el sanitizador del carrito, y los tokens del comerciante como{{total_price}}ya están resueltos. - Los precios que llegan como
stringya están formateados en el formato de dinero de la tienda. Los precios comonumberestán en centavos. Un bloque te da uno u otro, y la tabla de cada bloque indica cuál. isLoadingsiempre esfalsedentro de una plantilla. El bloque renderiza su skeleton integrado y solo llama a tu plantilla una vez que el carrito se ha cargado, así que la prop se pasa por completitud más que para que ramifiques sobre ella.
Algunos bloques no devuelven nada en ciertos estados, así que tu plantilla nunca es llamada con datos vacíos. La plantilla de Rewards nunca ve un
milestones vacío, y la plantilla de Subscription upgrade nunca ve un view nulo. La referencia de cada bloque indica dónde aplica esto, así que puedes omitir la rama del estado vacío.
Así que
cart-internal-header__title es lo que hace que el título se vea como el título integrado, y cart-external-header__title es el asidero que debes usar cuando quieres cambiar cómo se ve.
Si estás reordenando elementos, cambiando etiquetas o agregando algo dentro de la estructura existente, deja los classnames como están. Conservas gratis la apariencia integrada, y rediseñas mediante Custom CSS apuntando a los ganchos cart-external-*.
Cuando estás cambiando la estructura del DOM en lugar de ajustarla, quita ambas familias de tu marcado y usa tus propios classnames en su lugar. Hay una razón distinta para cada una.
Elimina cart-internal-* porque el CSS integrado fue escrito para el DOM integrado. Mantén esas clases en marcado reestructurado y heredarás reglas de layout que asumen elementos que ya no tienes: contenedores flex que esperan otros hijos, espaciado entre elementos que se movieron, posicionamiento relativo a algo que eliminaste. Esto suele manifestarse como que tu propio CSS “no funciona” cuando en realidad las reglas integradas son las que están ganando.
Dos formas de dar estilo a lo que has construido:
Lo mejor para cualquier cosa que vayas a mantener o reutilizar. Dale a tus clases un prefijo con el que nadie más colisione, normalmente el nombre de tu tienda o marca:
.header o .title corre el riesgo de colisionar con las clases propias del carrito, la plantilla de otra app o un bloque futuro.
Sin ida y vuelta al panel de CSS, y todo vive en un solo lugar:
:hover ni otras pseudoclases, sin media queries y sin reutilización entre bloques. Recurre a la Opción 1 cuando quieras cualquiera de esas cosas.
El carrito se renderiza en un shadow root, así que la hoja de estilos de tu tema no puede alcanzar su interior. Los estilos de una plantilla personalizada tienen que venir del panel Custom CSS propio del carrito o de estilos inline, no de tu tema. Consulta Custom CSS.
Como el bloque desaparece silenciosamente en lugar de mostrar un error visible, verifica siempre una plantilla en vista previa antes de publicar. Si un bloque ha desaparecido, abre primero la consola del navegador.
Dos cosas contra las que vale la pena protegerse, ya que ambas hacen crashear una plantilla que asume lo contrario:
- Props anulables. Muchas props son
nullen condiciones normales (logoUrlsin logo,imageUrlsin imagen,variantTitleen un producto de una sola variante). Verifícalas antes de usarlas. - Arrays que pueden estar vacíos.
discountTagsydiscountCodesson[]mucho más a menudo que no.
- Las plantillas personalizadas son anulaciones de visualización. Para ejecutar lógica contra el carrito (suscribirte a eventos, agregar artículos, reaccionar a cambios), usa Scripts personalizados y el Cart SDK.
- Casi todos los bloques admiten una. Las excepciones son el bloque Express payments, que aloja los propios botones de pago de Shopify, y el contenedor Cart items en sí, aunque la fila Product dentro de él sí admite una plantilla personalizada.
- Una plantilla no puede cambiar lo que un bloque hace fundamentalmente. Cambia cómo se presentan los datos del bloque, no los datos ni el comportamiento detrás de ellos.
El bloque Custom code es la única superficie que agrega marcado en lugar de reemplazar el renderizado de un bloque, así que sus props son diferentes: todo el carrito, más una acción de agregar al carrito. Consulta Bloques de código personalizado → Props.