Perché Horizon Non Ha main-cart-items.liquid (e Come Personalizzare cart-items-component Invece)

Horizon non ha un file di sezione main-cart-items.liquid. Quel file esiste in Dawn, non in Horizon. In Horizon, il rendering degli articoli del carrello è gestito da main-cart.liquid (la sezione) insieme all'elemento web personalizzato cart-items-component, e la personalizzazione del carrello significa lavorare all'interno di quell'architettura web-component anziché modificare una sezione Liquid piatta.

Punti chiave

• Horizon ha sostituito il pattern monolitico main-cart-items.liquid con un web component autonomo cart-items-component.
• Modificare direttamente i file core di Horizon verrà sovrascritto al prossimo aggiornamento del tema (Horizon rilascia aggiornamenti settimanali).
• Gli attributi del carrello vanno in main-cart-footer.liquid; le proprietà delle voci sono rese tramite iterazione cart.items dentro main-cart.liquid.
• Il percorso di personalizzazione sicuro è: nuovi file di blocco in blocks/, file di sezione con prefisso e un ramo upstream GitHub per estrarre gli aggiornamenti di Shopify in modo pulito.
• Le app costruite per l'architettura Online Store 2.0 più vecchia spesso si rompono su Horizon perché i web component vengono eseguiti dentro Shadow DOM.

Perché il File che Stai Cercando Non Esiste

La documentazione di Shopify e innumerevoli tutorial fanno riferimento a main-cart-items.liquid perché è così che Dawn struttura il suo carrello. Dawn divide la pagina del carrello in due sezioni: main-cart-items.liquid (la tabella delle voci) e main-cart-footer.liquid (totali, pulsante di checkout, attributi). Horizon non replica questa divisione.

Horizon è il fiore all'occhiello di una nuova generazione di temi Shopify costruito sul framework Horizon. Il principio architetturale è: ogni pezzo interattivo significativo della pagina è un elemento web personalizzato autonomo. Il cassetto del carrello, il selettore di varianti, la ricerca predittiva, nessuno di essi è una sezione Liquid monolitica nel modo in cui Dawn li implementa. Invece, sono elementi personalizzati incapsulati composti insieme all'interno di un singolo file di sezione main-cart.liquid.

Ciò ha causato confusione immediata quando Horizon è stato lanciato a Summer Editions 2025. A febbraio 2026, i forum della comunità Shopify erano pieni di commercianti su Horizon 3.3.0 che cercavano main-cart-items.liquid nella loro directory sections/ e non trovavano nulla, perché non era mai stata lì.

Come Appare Effettivamente l'Architettura del Carrello Horizon

Invece di un file di sezione separato per ogni zona del carrello, la pagina del carrello di Horizon è strutturata attorno a main-cart.liquid come sezione esterna, con l'elemento personalizzato <cart-items-component> che gestisce il rendering interattivo delle voci all'interno di esso.

Le decisioni architettoniche chiave, direttamente dal repository GitHub ufficiale di Horizon:

• Reso lato server in primo luogo. L'HTML viene reso dai server di Shopify tramite Liquid. La logica aziendale come la formattazione del denaro e le traduzioni rimane sul server, non sul client.
• Miglioramento progressivo nativo del web. Il tema si rivolge ai browser moderni senza polyfill, e il re-rendering asincrono dello stato del carrello (aggiornamenti della quantità, rimozioni) viene gestito con parsimonia come un miglioramento progressivo in cima all'HTML reso dal server.
• JavaScript con ambito. Horizon include una classe JS specifica che misura le prestazioni per componenti come il modulo di prodotto, il cassetto del carrello e lo sconto del carrello, mantenendo il peso di JS minimo per componente.

L'elemento cart-items-component è l'elemento personalizzato (<cart-items-component>) che avvolge la tabella delle voci. Ascolta gli eventi di modifica del carrello (aggiungi, rimuovi, aggiorna quantità) e re-esegue il rendering del suo HTML interno tramite l'API Cart Ajax senza un ricaricamento completo della pagina. Il suo template Liquid vive all'interno di main-cart.liquid, non in un file separato.

Gli attributi del carrello (campi personalizzati a livello di ordine come un messaggio regalo o un selettore di data) vengono acquisiti tramite main-cart-footer.liquid. Per la documentazione del template del carrello di Shopify, aggiungi un <input> con name="attributes[your-field-name]" e form="cart" all'interno di quel file di footer. Quell'attributo è quindi accessibile tramite {{ cart.attributes['your-field-name'] }}.

Le proprietà delle voci (dati personalizzati per prodotto) non vengono rese automaticamente da cart-items-component. Devi eseguire il ciclo di cart.items all'interno di main-cart.liquid e restituire l'hash .properties di ogni articolo. La documentazione di Shopify nota che se lo stesso articolo viene aggiunto due volte con proprietà di voci di riga univoche, si dividono in voci separate, un comportamento degno di considerazione nella logica del tuo template.

Come Personalizzare il Carrello in Sicurezza su Horizon

Horizon rilascia aggiornamenti settimanali dei temi. Se modifichi i file core direttamente, tali modifiche verranno sovrascritte al prossimo aggiornamento. Il repository GitHub ha persino segnalato una discrepanza di versione dal vivo: a partire da aprile 2026, il Theme Store era alla v3.5.1 mentre il repository GitHub era bloccato alla v3.4.0, il che significa che alcuni cambiamenti arrivavano nello store prima. Questo sottolinea la necessità di un flusso di lavoro Git appropriato.

La configurazione GitHub a tre rami

La guida ufficiale di Shopify Growth Services (pubblicata a novembre 2025) consiglia di gestire tutte le personalizzazioni di Horizon attraverso una strategia di branching disciplinata:

1. upstream/horizon, traccia il repository ufficiale Shopify/horizon direttamente. Qui estrai prima gli aggiornamenti.
2. main, il tuo ramo personalizzato e pronto per la produzione. Unisci upstream in main dopo aver riveduto i diff.
3. Rami di funzionalità, tutte le nuove personalizzazioni del carrello vengono costruite qui e sottoposte a PR in main.

Per configurare l'upstream, accedi alla tua cartella del tema locale ed esegui:

git remote add upstream https://github.com/Shopify/horizon.git
git fetch upstream

Quando Shopify spedisce una nuova versione di Horizon, estraiala nel tuo ramo upstream, risolvi i conflitti nei tuoi file personalizzati e unisci. Ciò mantiene le tue personalizzazioni del carrello intatte in ogni aggiornamento settimanale.

Dove mettere effettivamente le personalizzazioni del carrello

Evita la tentazione di copiare l'intero main-cart.liquid in una versione con prefisso custom. a meno che non sia assolutamente necessario. Una copia completa significa che devi differenziare manualmente e ri-applicare ogni futuro aggiornamento di Shopify a quella sezione. Invece, aggiungi solo ciò di cui hai bisogno nei nuovi file di blocco dove possibile, e mantieni la sezione core intatta.

Costruzione di estensioni del carrello interattive come web component

La filosofia delle prestazioni di Horizon è esplicita: niente librerie esterne di carousel o UI. Se hai bisogno di comportamenti interattivi all'interno del carrello (uno stepper di quantità animato, una barra di progresso di spedizione gratuita in tempo reale), costruiscilo come un Web Component vanilla che si inizializza solo quando è visibile. Usa IntersectionObserver per differire l'inizializzazione su tutto ciò che non è immediatamente nel viewport, e scrivi i tuoi stili all'interno di tag {% style %} per mantenerli con ambito e liberi da richieste HTTP extra.

class CartUpsellBadge extends HTMLElement {
  connectedCallback() {
    // Inizializza solo quando il carrello è aperto / elemento è visibile
    this._observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        this._init();
        this._observer.disconnect();
      }
    });
    this._observer.observe(this);
  }

  _init() {
    // Recupera dati di upsell, esegui il rendering in this.innerHTML
  }
}
customElements.define('cart-upsell-badge', CartUpsellBadge);

Carica questo script tramite <script type="module"> in modo che il browser lo gestisca in modo efficiente, abbinandosi al pattern di caricamento dello script di Horizon.

Il Problema di Compatibilità delle App Shadow DOM

Questo è il trucco che cattura la maggior parte dei commercianti a metà progetto. Le app costruite per l'architettura Online Store 2.0 più vecchia di Dawn spesso si collegano al carrello interrogando il DOM per un input di quantità o un span di totale del carrello e ascoltando gli eventi di modifica. Quel pattern si rompe su Horizon.

Poiché i componenti del carrello di Horizon sono web component, le app che utilizzano l'incapsulamento Shadow DOM bloccano il vecchio pattern document.querySelector('.cart-item__quantity'). Gli interni dell'elemento personalizzato non sono accessibili dall'esterno della shadow root tramite query DOM standard.

Prima di installare qualsiasi app del carrello su Horizon, verifica esplicitamente la nota "supporto Horizon" nel listato dell'app. Le app che hanno ricevuto un badge "Built for Shopify" sono state testate per le prestazioni, ma lo stato del badge da solo non garantisce la compatibilità di Shadow DOM. In caso di dubbio, installa su un tema duplicato e testa aggiornamenti di quantità, rimozioni e il flusso di checkout end-to-end prima di andare live.

Il Ritardo GitHub Attuale e Cosa Significa per Te

A partire da metà 2026, il repository GitHub Shopify/horizon ha avuto periodi in cui è rimasto indietro rispetto alla versione dal vivo nel Theme Store. Ad aprile 2026, i sviluppatori della comunità hanno notato che il repo era alla v3.4.0 mentre il Theme Store serviva v3.5.1. Shopify ha confermato che il ramo principale può includere codice per funzionalità non ancora rilasciate, il che significa che il tema pubblicato e il repo possono essere fuori sincronizzazione in entrambe le direzioni.

Implicazione pratica: non trattare il repository GitHub come la fonte canonica della versione in esecuzione nel tuo negozio. Estrai l'ultimo tema dal tuo admin di Shopify (Online Store > Temi > Scarica file del tema) e differenzialo rispetto al repository GitHub prima di fare supposizioni su quale codice è live. Usa Theme Check (incluso in Shopify CLI e disponibile come estensione VS Code che Horizon raccomanda automaticamente) per convalidare il tuo Liquid prima di ogni distribuzione.

Una Nota sul Bug del Browser In-App di Instagram (Giugno 2026)

Un problema dal vivo degno di nota: a partire dalla settimana del 14 giugno 2026, più commercianti di Horizon hanno segnalato che la navigazione ulteriore dopo il caricamento della pagina iniziale all'interno dei browser in-app di Instagram, Facebook e TikTok produce una schermata bianca vuota. Il team dei temi di Shopify ha riconosciuto il problema il 17 giugno 2026, confermato che esiste una soluzione alternativa e ha affermato che la causa principale potrebbe essere correlata al comportamento del browser in-app piuttosto che al tema stesso. Se stai eseguendo campagne di social commerce che guidano il traffico attraverso questi browser in-app, contatta il supporto Shopify per la soluzione alternativa attuale mentre la correzione completa è in corso.

Riepilogo: Il Modello Mentale Corretto per il Carrello di Horizon

Smetti di cercare main-cart-items.liquid. È un concetto di Dawn. Il carrello di Horizon è:

• Una sezione esterna: main-cart.liquid
• Un web component interattivo: <cart-items-component> che gestisce i re-render Ajax
• Una sezione footer: main-cart-footer.liquid per gli attributi del carrello e il modulo di checkout
• Directory blocchi: dove vivono tutti i tuoi aggiunte personalizzate

Lavora all'interno di quel modello, gestisci le tue modifiche attraverso un appropriato ramo upstream GitHub, e puoi personalizzare in sicurezza il carrello di Horizon senza temere ogni aggiornamento settimanale.

Se hai bisogno di aiuto pratico per costruire un'esperienza di carrello personalizzata su Horizon, vedi cosa facciamo come sviluppatore di temi Shopify o controlla il nostro servizio di ottimizzazione della velocità di Shopify se le prestazioni del carrello sono la preoccupazione sottostante.