Skip to main content
Un modèle personnalisé vous permet de remplacer le rendu d’un bloc individuel. Au lieu de l’interface intégrée du bloc, le panier affiche votre propre JSX, en utilisant les mêmes données que le bloc utiliserait normalement. Il s’agit d’une capacité transversale plutôt que d’un bloc à part entière : la plupart des blocs l’exposent depuis leur onglet Code. Cette page couvre ce qui s’applique à tous les blocs. Pour les props qu’un bloc spécifique vous fournit, consultez la référence du bloc en question.

​
Modèle personnalisé vs bloc Custom code

Ces deux notions se ressemblent mais font des choses différentes :
  • Un modèle personnalisé remplace le rendu d’un bloc existant par votre propre balisage, et vous fournit les données propres à ce bloc (le titre et le nombre d’articles du Header, les totaux du Summary, etc.). Il n’ajoute rien de nouveau ; il restyle un bloc.
  • Le bloc Custom code ajoute un nouveau bloc de HTML ou de React arbitraire n’importe où dans le panier.
Optez pour un modèle personnalisé lorsque le bloc intégré est presque adapté mais que vous avez besoin d’une mise en page ou d’un balisage différent. Optez pour un bloc Custom code lorsque vous voulez ajouter quelque chose que les blocs intégrés ne couvrent pas.

​
Utiliser un modèle personnalisé

  1. Sélectionnez un bloc dans l’éditeur et ouvrez son onglet Code.
  2. Modifiez le modèle par défaut. Les modèles personnalisés sont uniquement en JSX (le choix HTML-ou-JSX est exclusif au bloc Custom code).
  3. Cliquez sur Compile. La compilation supprime les types et transpile le JSX, elle attrape donc les erreurs de syntaxe. Les erreurs de type n’empêchent pas la compilation : l’éditeur les signale en ligne pendant que vous tapez, avec le même IntelliSense qui autocomplète les props du bloc.
  4. Activez le modèle pour que le panier l’utilise à la place du rendu intégré.
  5. Reset to default restaure à tout moment le modèle d’origine du bloc.

​
Écrire un modèle avec l’IA

L’onglet Code comprend un bouton Copy AI prompt (icône de baguette ✦). Cliquer dessus copie dans votre presse-papiers un brief autonome que vous pouvez coller directement dans une session de chat avec une IA (Claude, ChatGPT ou similaire). Le prompt contient tout ce dont l’IA a besoin pour écrire un modèle valide pour ce bloc spécifique :
  • Les règles de compilation (expression unique, pas de export default, pas d’imports)
  • Les props exactes que le bloc reçoit, correspondant à ce qu’affiche l’IntelliSense de l’éditeur
  • La signature de fonction verrouillée imposée par l’éditeur
  • Les règles propres au bloc (formats monétaires, gestionnaires à connecter, exigences d’accessibilité)
  • Une section à compléter où vous collez votre modèle actuel et décrivez la modification souhaitée
Après la copie, ouvrez une session d’IA, collez le prompt, complétez les deux champs vides en bas (votre modèle actuel et la modification souhaitée), puis envoyez. L’IA renvoie un modèle complet que vous pouvez coller à nouveau dans l’éditeur et compiler.
Collez votre modèle existant dans la section à compléter plutôt que de la laisser vide. L’IA l’utilise comme point de départ, de sorte que toute personnalisation déjà effectuée est conservée au lieu d’être remplacée par le modèle par défaut.
Le prompt est spécifique à chaque bloc. Le bouton Copy AI prompt n’apparaît que sur les blocs qui prennent en charge les modèles personnalisés.
Le modèle par défaut à partir duquel vous démarrez est une copie fonctionnelle du balisage intégré du bloc, vous disposez donc toujours d’une référence correcte et fonctionnelle à modifier plutôt que d’une page vierge. Utilisez Reset to default chaque fois que vous voulez retrouver cette référence.Ce n’est pas toujours une correspondance octet par octet. Le modèle par défaut du Header affiche également logoUrl, pour lequel le balisage intégré ne prévoit aucun emplacement, donc l’activation de ce modèle est ce qui fait apparaître pour la première fois une image d’en-tête téléversée.

​
Ce que votre modèle remplace

Un modèle remplace entièrement le rendu du bloc. Il ne reste aucun wrapper autour de votre JSX, ce qui a des conséquences à connaître avant de commencer à supprimer des éléments :
L’onglet Design est le piège le plus fréquent. Tant qu’un modèle personnalisé est actif, les champs de l’onglet Design sont désactivés et une icône d’avertissement apparaît à côté de l’en-tête « Design ». Survolez l’icône pour en connaître la raison. Stylisez plutôt le bloc depuis votre modèle, soit en inline, soit avec votre propre CSS. Les champs sont réactivés dès que vous désactivez le modèle personnalisé.
Ce que vous conservez : la position du bloc dans le panier, son interrupteur de visibilité, ses paramètres (qui alimentent toujours les props que vous recevez), le panneau Custom CSS du panier et le squelette de chargement intégré. Ce dernier point surprend souvent. Le bloc vérifie si le panier est encore en cours de chargement avant d’atteindre votre modèle, donc le squelette intégré s’affiche pendant le chargement et votre modèle ne s’exécute qu’une fois le panier prêt. Vous n’avez pas à construire d’état de chargement.

​
Ce qui est disponible dans un modèle

Votre modèle est un composant fonction unique. Il est compilé à partir de TSX, donc les annotations de type sont autorisées et supprimées à la compilation. C’est pourquoi les modèles par défaut sont écrits avec :
La ligne de signature et l’accolade fermante sont verrouillées. L’éditeur ne vous laisse modifier ni l’une ni l’autre, et le survol affiche “Locked — this line can’t be edited.” Vous écrivez le corps entre les deux. Reset to default est la seule chose qui peut les remplacer. Ce qui compte aussi :
  • Vous disposez de cinq hooks : useState, useEffect, useMemo, useRef et useCallback. Plus Fragment, pour <>…</>.
  • Il n’y a aucun import. Vous ne pouvez rien import, et il n’y a pas d’objet React dans la portée, donc pas de React.useReducer, pas de React.Children. Si un hook n’est pas dans la liste ci-dessus, il n’est pas disponible.
  • Les props sont en lecture seule. Muter une prop ne servira à rien. Pour modifier le panier, utilisez les props gestionnaires que le bloc vous fournit (onClose, increment, selectPlan, etc.) plutôt que d’écrire directement dans les props.
  • window est accessible, donc un modèle peut appeler le Cart SDK via window.aftersell.cart lorsqu’il a besoin de quelque chose que les props du bloc ne couvrent pas.

​
Conventions communes à tous les blocs

Trois règles s’appliquent partout, et les connaître élimine la majeure partie des tâtonnements :
  • Les props *Html sont du texte enrichi pré-assaini. Affichez-les avec dangerouslySetInnerHTML. Elles sont déjà passées par l’assainisseur du panier, et les jetons marchands comme {{total_price}} sont déjà résolus.
  • Les prix qui arrivent en tant que string sont déjà formatés dans le format monétaire de la boutique. Les prix en tant que number sont en centimes. Un bloc vous donne l’un ou l’autre, et le tableau de chaque bloc précise lequel.
  • isLoading est toujours false dans un modèle. Le bloc affiche son squelette intégré et n’appelle votre modèle qu’une fois le panier chargé, donc la prop est transmise par souci d’exhaustivité plutôt que pour que vous fassiez des branchements dessus.
Quelques blocs ne renvoient rien du tout dans certains états, de sorte que votre modèle n’est jamais appelé avec des données vides. Le modèle Rewards ne voit jamais un milestones vide, et le modèle Subscription upgrade ne voit jamais une view nulle. La référence de chaque bloc indique où cela s’applique, pour que vous puissiez ignorer la branche d’état vide.

​
Styliser un modèle personnalisé

Le modèle par défaut à partir duquel vous démarrez porte les classnames du bloc. La façon de styliser vos modifications dépend de la distance que vous prenez par rapport à ce point de départ.

​
Les deux familles de classes

Chaque élément d’un modèle par défaut porte un classname apparié, et ils ont des rôles très différents : Ainsi, cart-internal-header__title est ce qui donne au titre l’apparence du titre intégré, et cart-external-header__title est la poignée que vous êtes censé saisir lorsque vous voulez changer son apparence.

​
Petites modifications : conservez les deux classnames

Si vous réordonnez des éléments, changez des libellés ou ajoutez quelque chose à l’intérieur de la structure existante, laissez les classnames tels quels. Vous conservez gratuitement l’apparence intégrée, et vous restylez via Custom CSS en ciblant les points d’accroche cart-external-*.

​
Restructuration : supprimez les deux classnames

Dès que vous modifiez la structure du DOM plutôt que de l’ajuster, retirez les deux familles de votre balisage et utilisez plutôt vos propres classnames. Il y a une raison distincte pour chacune. Supprimez cart-internal-* parce que le CSS intégré a été écrit pour le DOM intégré. Conservez ces classes sur un balisage restructuré et vous héritez de règles de mise en page qui supposent des éléments que vous n’avez plus : des conteneurs flex attendant d’autres enfants, des espacements entre des éléments déplacés, un positionnement relatif à quelque chose que vous avez supprimé. Cela se manifeste généralement par votre propre CSS qui « ne fonctionne pas » alors que ce sont les règles intégrées qui l’emportent.
Supprimez cart-external-* parce que c’est un nom partagé, pas le vôtre. Ces classnames signifient quelque chose de précis sur le balisage intégré, et votre Custom CSS est écrit une seule fois pour tout le panier. Si un modèle restructuré les réutilise, toute règle que vous écrivez cible à la fois votre structure et la structure intégrée.Cela tourne mal dès que vous désactivez le modèle personnalisé : le bloc revient à son balisage intégré, et votre CSS le cible toujours, stylisant désormais un DOM pour lequel il n’a jamais été écrit. Votre propre préfixe maintient les deux proprement séparés, de sorte que désactiver un modèle est un retour en arrière propre.
Deux façons de styliser ce que vous avez construit :

​
Option 1 : vos propres classnames plus Custom CSS

Idéal pour tout ce que vous allez maintenir ou réutiliser. Donnez à vos classes un préfixe avec lequel personne d’autre n’entrera en collision, généralement le nom de votre boutique ou de votre marque :
Puis, dans l’éditeur de panier, sélectionnez Cart settings dans le panneau de gauche et ouvrez l’onglet Custom CSS à droite :
Un préfixe compte plus qu’il n’y paraît. Sans préfixe, une classe comme .header ou .title risque d’entrer en collision avec les classes propres du panier, le modèle d’une autre application ou un futur bloc.

​
Option 2 : styles inline

Pas d’aller-retour avec le panneau CSS, et tout se trouve au même endroit :
Adapté pour l’échafaudage de mise en page et les cas ponctuels. Ses limites sont les habituelles : pas de :hover ni d’autres pseudo-classes, pas de media queries, et pas de réutilisation entre blocs. Passez à l’option 1 dès que vous avez besoin de l’un de ces éléments.

​
Choisir une approche

Le panier est rendu dans un shadow root, donc la feuille de style de votre thème ne peut pas y pénétrer. Les styles d’un modèle personnalisé doivent provenir du panneau Custom CSS du panier ou de styles inline, pas de votre thème. Consultez Custom CSS.

​
Quand un modèle échoue

Un modèle défaillant ne casse jamais le panier. Le bloc n’affiche rien et tout ce qui l’entoure continue de fonctionner, ce qui est sûr mais facile à manquer : un espace vide à l’emplacement de votre bloc est le symptôme. Comme le bloc disparaît silencieusement plutôt que d’afficher une erreur visible, vérifiez toujours un modèle en prévisualisation avant de publier. Si un bloc a disparu, ouvrez d’abord la console du navigateur. Deux points méritent des garde-fous, car les deux font planter un modèle qui suppose le contraire :
  • Les props nullables. De nombreuses props sont null dans des conditions normales (logoUrl sans logo, imageUrl sans image, variantTitle sur un produit à variante unique). Vérifiez avant de les utiliser.
  • Les tableaux qui peuvent être vides. discountTags et discountCodes valent [] bien plus souvent qu’autrement.

​
Limitations

  • Les modèles personnalisés sont des remplacements d’affichage. Pour exécuter une logique sur le panier (s’abonner aux événements, ajouter des articles, réagir aux modifications), utilisez les Scripts personnalisés et le Cart SDK.
  • Presque tous les blocs en prennent un en charge. Les exceptions sont le bloc Express payments, qui héberge les boutons de paiement propres à Shopify, et le conteneur Cart items lui-même, bien que la ligne Product qu’il contient prenne en charge un modèle personnalisé.
  • Un modèle ne peut pas changer ce qu’un bloc fait fondamentalement. Il change la façon dont les données du bloc sont présentées, pas les données ni le comportement sous-jacent.

​
Props de chaque bloc

Chaque bloc transmet ses propres données. Le tableau complet des props, avec les types et un exemple concret, se trouve sur la page de ce bloc : Le bloc Custom code est la seule surface qui ajoute du balisage plutôt que de remplacer le rendu d’un bloc, donc ses props sont différentes : le panier entier, plus une action d’ajout au panier. Consultez Blocs de code personnalisé → Props.