Neden Horizon'da main-cart-items.liquid Yok (ve Bunun Yerine cart-items-component Nasıl Özelleştirilir)

Horizon'da main-cart-items.liquid bölüm dosyası yoktur. Bu dosya Dawn'da mevcuttur, Horizon'da değil. Horizon'da sepet öğesi işlenmesi, main-cart.liquid (bölüm) ile birlikte cart-items-component özel web öğesi tarafından yönetilir ve sepeti özelleştirmek, düz bir Liquid bölümü düzenlemek yerine web bileşeni mimarisi içinde çalışmak anlamına gelir.

Temel öğrenme noktaları

• Horizon, monolitik main-cart-items.liquid desenini, kendine yeterli cart-items-component web bileşeni ile değiştirdi.
• Çekirdek Horizon dosyalarını doğrudan düzenlemek sonraki tema güncellemesinde silinecektir (Horizon haftalık sürümler yayınlar).
• Sepet nitelikleri main-cart-footer.liquid içine gider; satır öğesi özellikleri main-cart.liquid içinde cart.items yinelemesi aracılığıyla işlenir.
• Güvenli özelleştirme yolu şudur: blocks/ içinde yeni blok dosyaları, ön ek eklenmiş bölüm dosyaları ve Shopify güncellemelerini temiz bir şekilde çekmek için bir GitHub upstream dalı.
• Eski Online Store 2.0 mimarisi için yapılandırılmış uygulamalar, web bileşenleri Shadow DOM içinde çalıştığı için Horizon'un sepetinde sıklıkla kırılır.

Aradığınız Dosya Neden Yoktur

Shopify'ın yardım dokümanları ve sayısız öğretici main-cart-items.liquid dosyasından bahseder çünkü bu, Dawn'un sepetini nasıl yapılandırdığıdır. Dawn sepet sayfasını iki bölüme ayırır: main-cart-items.liquid (satır öğesi tablosu) ve main-cart-footer.liquid (toplamlar, kasa butonu, nitelikler). Horizon bu bölünmeyi çoğaltmaz.

Horizon, Horizon çerçevesi üzerinde inşa edilmiş yeni nesil Shopify temalarının amiral gemisidir. Mimari ilkesi şudur: sayfanın her anlamlı etkileşimli parçası, kendine yeterli bir web bileşenidir. Sepet çekmeceği, varyant seçici, tahmine dayalı arama, hiçbiri Dawn'un uyguladığı monolitik Liquid bölümleri değildir. Bunun yerine, tek bir main-cart.liquid bölüm dosyası içinde bir araya getirilen kapsüllü özel öğelerdir.

Bu, Horizon, Summer Editions 2025'te başlatıldığında hemen karışıklığa neden oldu. Şubat 2026'ya kadar, Shopify Topluluğu forumları Horizon 3.3.0'da olan ve sections/ dizininde main-cart-items.liquid dosyasını arayan ve hiçbir şey bulamayan işletmecilerle doluydu çünkü bu dosya hiç orrada olmamıştır.

Horizon Sepet Mimarisi Gerçekte Neye Benziyor

Sepet alanı başına ayrı bir bölüm dosyası yerine, Horizon'un sepet sayfası main-cart.liquid etrafında yapılandırılmıştır ve <cart-items-component> özel öğesi içinde etkileşimli satır öğesi işlemesini yönetir.

Temel mimari kararlar, resmi Horizon GitHub deposundan doğrudan:

• İlk olarak sunucu tarafından işlenir. HTML, Shopify'ın sunucuları tarafından Liquid aracılığıyla işlenir. Para biçimi ve çeviriler gibi işletme mantığı istemcide değil sunucuda kalır.
• Web-yerel aşamalı geliştirme. Tema, polifilleri olmadan modern tarayıcıları hedefler ve sepet durumunun (miktar güncellemeleri, kaldırmalar) zaman uyumsuz yeniden işlenmesi, sunucu tarafından işlenen HTML'nin üstünde aşamalı bir geliştirme olarak seyrek şekilde yönetilir.
• Kapsamlı JavaScript. Horizon, ürün formu, sepet çekmecesi ve sepet indirimi gibi bileşenler için performansı ölçen belirli bir JS sınıfı içerir ve bileşen başına JS ağırlığını minimum tutar.

cart-items-component, satır öğesi tablosunu sarmalayan özel öğedir (<cart-items-component>). Sepet değişikliği olaylarını (ekleme, kaldırma, miktar güncellemesi) dinler ve iç HTML'sini, tam sayfa yeniden yükleme olmadan Sepet Ajax API'si aracılığıyla yeniden işler. Liquid şablonu, ayrı bir dosyada değil main-cart.liquid içinde bulunur.

Sepet nitelikleri (hediye mesajı veya tarih seçici gibi sipariş düzeyinde özel alanlar) main-cart-footer.liquid aracılığıyla yakalanır. Shopify'ın sepet şablonu belgelerine göre, bu alt bilgi dosyası içine name="attributes[your-field-name]" ve form="cart" ile bir <input> eklersiniz. Bu nitelik daha sonra {{ cart.attributes['your-field-name'] }} aracılığıyla erişilebilir hale gelir.

Satır öğesi özellikleri (ürün başına özel veriler) cart-items-component tarafından otomatik olarak işlenmez. main-cart.liquid içinde cart.items döngüsüne ihtiyacınız vardır ve her öğenin .properties hash'ini çıktı almanız gerekir. Shopify'ın kendi belgeleri, aynı öğenin benzersiz satır öğesi özellikleri ile iki kez eklenirse, ayrı satır öğelerine bölündüğünü ve bu davranışın şablon mantığınızda hesaba katılmaya değer olduğunu belirtir.

Horizon'da Sepeti Güvenli Bir Şekilde Nasıl Özelleştirilir

Horizon haftalık tema güncellemeleri yayınlar. Çekirdek dosyaları doğrudan düzenlerseniz, bu düzenlemeler sonraki güncellemede silinecektir. GitHub deposu, canlı bir sürüm tutarsızlığını bile işaretlemiştir: Nisan 2026 itibariyle, Tema Mağazası v3.5.1'deyken GitHub deposu v3.4.0'a sabitlenmiştir, bu da bazı değişikliklerin önce mağazaya gelmekte olduğu anlamına gelir. Bu, uygun bir Git iş akışına olan ihtiyacı güçlendirir.

Üç daldan oluşan GitHub kurulumu

Shopify'ın resmi Growth Services rehberi (Kasım 2025'te yayınlandı), tüm Horizon özelleştirmelerini disiplinli bir dallanma stratejisi aracılığıyla yönetmeyi önerir:

1. upstream/horizon, resmi Shopify/horizon deposunu doğrudan izler. Önce güncellemeleri burada çekersiniz.
2. main, özelleştirilmiş, üretime hazır dalınız. Farklılıkları inceledikten sonra upstream'i ana dalına birleştirirsiniz.
3. Özellik dalları, tüm yeni sepet özelleştirmeleri burada oluşturulur ve ana dalına PR'lanır.

Upstream'i ayarlamak için yerel tema klasörüne gidin ve çalıştırın:

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

Shopify yeni bir Horizon sürümü yayınladığında, upstream dalınızda çekin, özel dosyalarınızda çatışmaları çözün ve birleştirin. Bu, sepet özelleştirmelerinizi her haftalık güncellemede tutarlı tutar.

Sepet özelleştirmelerinizi nereye koymalısınız

Tam main-cart.liquid dosyasını bir custom. ön ekli versiyonuna kopyalamaya olan kötü alışkanlığı önleyin, mutlaka ihtiyacınız olmadığı sürece. Tam bir kopya, her gelecek Shopify güncellemesini bu bölüme el ile diff etmeniz ve yeniden uygulamanız gerektiği anlamına gelir. Bunun yerine, mümkün olan yerlerde yalnızca ihtiyacınız olanı yeni blok dosyalarında ekleyin ve çekirdek bölümü dokunmadan tutun.

Web bileşenleri olarak etkileşimli sepet uzantıları oluşturma

Horizon'un performans felsefesi açıktır: harici karusel veya UI kütüphanesi yok. Sepet içinde etkileşimli davranışa ihtiyacınız varsa (animasyonlu miktar adım, gerçek zamanlı ücretsiz kargo ilerleme çubuğu), görünür olduğunda yalnızca başlatılan vanilla Web Bileşeni olarak oluşturun. IntersectionObserver kullanarak görüntü alanında olmayan herhangi bir şeyin başlatılmasını erteleyin ve stillerinizi {% style %} etiketleri içinde yazarak bunları kapsamlı ve ekstra HTTP isteklerinden arınmış tutun.

class CartUpsellBadge extends HTMLElement {
  connectedCallback() {
    // Sepet açıldığında / öğe görüntülendeyken başlat
    this._observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        this._init();
        this._observer.disconnect();
      }
    });
    this._observer.observe(this);
  }

  _init() {
    // Ek satış verisi getir, this.innerHTML'ye işle
  }
}
customElements.define('cart-upsell-badge', CartUpsellBadge);

Bu betiği <script type="module"> aracılığıyla yükleyin, böylece tarayıcı onu verimli bir şekilde yönetir, Horizon'un kendi betik yükleme düzeniyle eşleşir.

Shadow DOM Uygulaması Uyumluluğu Sorunu

Bu, çoğu işletmecinin proje ortasında yakalandığı hile. Dawn'un eski Online Store 2.0 mimarisi için yapılandırılmış uygulamalar, genellikle sepete miktar girişi veya sepet toplam span'ı için DOM'u sorgulamak ve değişiklik olaylarını dinlemek yoluyla bağlanırlar. Bu desen Horizon'da kırılır.

Horizon'un sepet bileşenleri web bileşenleri olduğundan, Shadow DOM kapsüllemeyi kullanan uygulamalar eski document.querySelector('.cart-item__quantity') desenini engeller. Özel öğenin içi, gölge kökün dışından standart DOM sorguları aracılığıyla erişilemez.

Herhangi bir sepet uygulamasını Horizon'a kurmadan önce, uygulama listesinde açıkça "Horizon desteği" notu olup olmadığını kontrol edin. "Shopify tarafından Yerleştirilmiş" rozeti alan uygulamalar performans açısından test edilmiştir, ancak rozet durumu tek başına Shadow DOM uyumluluğunu garantilemez. Şüphe durumunda, yinelenen bir temaya kurun ve canlı gitmeden önce miktar güncellemelerini, kaldırmaları ve kasa akışını baştan sona test edin.

Mevcut GitHub Gecikmesi ve Bunun Sizin İçin Anlamı

2026 ortası itibariyle, Shopify/horizon GitHub deposu Tema Mağazasında canlı olan sürümün gerisinde kaldığı dönemlere sahip olmuştur. Nisan 2026'da, topluluk geliştiricileri, depo v3.4.0'dayken Tema Mağazasının v3.5.1 sunduğunu belirttiler. Shopify, ana dal için henüz yayınlanmayan özellikler kodu içerebileceğini ve yayınlanan tema ile depo arasında her iki yönde de eşitleme sorunu yaşanabileceğini doğruladı.

Pratik çıkarım: GitHub deposunu, mağazada çalışan sürümün kanonik kaynağı olarak görmeyin. Varsayımlar yapmadan önce en son temayı Shopify yöneticinizden indirin (Çevrimiçi Mağaza > Temalar > Tema dosyasını indir) ve GitHub deposunun karşısında dif yapın. Tema Check'i (Shopify CLI'ye paketlenmiş ve Horizon'un otomatik olarak önerdiği VS Code uzantısı olarak mevcut) kullanarak her dağıtımdan önce Liquid'inizi doğrulayın.

Instagram Uygulama İçi Tarayıcı Hatası Hakkında Not (Haziran 2026)

Bilmek değer olan canlı bir sorun: 14 Haziran 2026 haftasından itibaren, birden fazla Horizon işletmecisi, Instagram'ın, Facebook'un ve TikTok'un uygulama içi tarayıcılarında ilk sayfa yüklemesinden sonra daha fazla gezinmenin beyaz bir ekran ürettiğini bildirmiştir. Shopify'ın tema ekibi, 17 Haziran 2026'da sorunu Topluluğu'nda kabul etti, bir geçici çözüm olduğunu doğruladı ve kök nedinin temadan ziyade uygulama içi tarayıcı davranışıyla ilişkili olabileceğini söyledi. Bu uygulama içi tarayıcılardan trafik gönderen sosyal ticaret kampanyaları yürütüyorsanız, tam çözüm devam ederken mevcut geçici çözüm için Shopify Desteği'ne başvurun.

Özet: Horizon'un Sepeti İçin Doğru Zihinsel Model

main-cart-items.liquid dosyasını aramayı bırakın. Bu, Dawn kavramıdır. Horizon'un sepeti şudur:

• Tek dış bölüm: main-cart.liquid
• Tek etkileşimli web bileşeni: Ajax yeniden işlemesini yöneten <cart-items-component>
• Tek alt bilgi bölümü: sepet nitelikleri ve kasa formu için main-cart-footer.liquid
• Bloklar dizini: tüm özel eklemelerinizin bulunduğu yerdir

Bu model içinde çalışın, değişikliklerinizi uygun bir GitHub upstream dalı aracılığıyla yönetin ve Horizon'un sepetini her haftalık güncellemeden korkmadan güvenli bir şekilde özelleştirebilirsiniz.

Horizon'da özel bir sepet deneyimi oluşturma konusunda uygulamalı yardıma ihtiyacınız varsa, Shopify tema geliştirici olarak yaptığımız işlemi görün veya sepet performansı temeldeki endişeyse Shopify hız optimizasyonu hizmetimizi kontrol edin.