Shopify Horizon Teması: main-cart.liquid ve cart-items-component Ustalaşması

Horizon temanızda main-cart-items.liquid aradıysanız ve bulamadıysanız, yalnız değilsiniz. Horizon, cart-items-component etrafında ortalanmış yerel web-component mimarisi ile Dawn döneminin bölüm modelini bilinçli olarak değiştirmiştir. Sepet mantığının gerçekte nerede yaşadığını ve Shopify'nin sonraki güncellemesinde kırılmadan nasıl genişletileceğini anlamak, Horizon'un sepetine dokunmadan önce yapabileceğiniz en önemli şeydir.

Ana çıkarımlar

• Horizon'da sections/ içinde main-cart-items.liquid yoktur; eşdeğeri main-cart.liquid artı cart-items-component web bileşenidir.
• Sepet bileşeni, DOM manipülasyonu yerine özel olaylar (cart:update, CartUpdateEvent) aracılığıyla iletişim kurar.
• Tüm sepet özelleştirmeleri, çekirdek Liquid dosyalarında düzenleme yapmadan blocks/ içinde yeni bloklar veya yeni snippet'ler içine gitmelidir.
• Horizon'un GitHub deposu (Shopify/horizon) yayınları takip eder, ancak Nisan 2026 itibariyle Theme Store sürümü (v3.5.1) genel depo (v3.4.0) öncesinde olmuştur, bu nedenle upstream'den çekmeden önce her zaman karşılaştırın.
• Uygulama blokları, üçüncü taraf sepet işlevselliği enjekte etmenin güvenli bir yoludur.

Horizon neden main-cart-items.liquid dosyasını kaldırdı

Her Dawn tabanlı özelleştirme öğreticisi size sections/main-cart-items.liquid açmayı söyler. Bu dosya, Dawn'da ve çoğu türevinde sepet tablosunu işleyen monolitik bölümdür. 21 Mayıs 2025'te Shopify Summer Editions 2025 sürümünde başlatılan Horizon, tamamen farklı bir yaklaşım benimser.

Horizon, bir büyük Liquid bölümü yerine sorumluluğu böler:

• sections/main-cart.liquid, sayfa iskeleti, renk düzeni ve {% content_for "blocks" %} işlemesine sahip üst düzey JSON-template bölümü.
• cart-items-component, tüm etkileşimli sepet satırı mantığına sahip yerel bir Web Bileşeni (JavaScript'te kaydedilen Özel Bir Öğe): miktar güncellemeleri, kaldırma düğmeleri, satır öğesi özellikleri ve Bölüm İşleme API'si yeniden işlemeler.

Bu bir tesadüf değildir. Horizon'un tasarım ilkeleri, Shopify/horizon GitHub deposunda belgelendirdiği gibi, Liquid aracılığıyla sunucu tarafından işlenen HTML'yi ve progresif geliştirme olarak az kullanılan, isteğe bağlı yeniden işlemeyi açıkça talep eder. Web bileşeni katmanı progresif kısmı işler; Liquid statik işlemeyi işler.

Gerçekten bilmeniz gereken Horizon dosya yapısı

Horizon'un kaynak ağacı Dawn'unkinden anlamlı bir şekilde farklıdır. Topluluk tarafından belgelenen mimari araştırmasına göre, tema şu şekilde gönderilir:

• assets/, 100'den fazla CSS, JS ve statik dosya
• blocks/, 94 tema bloğu Liquid dosyası, birden fazla bölüm arasında yeniden kullanılabilir
• sections/, 41 bölüm dosyası
• snippets/, 93 yeniden kullanılabilir Liquid snippet'i
• templates/, 14 JSON template dosyası

Sepet işi için, önemli olan dosyalar:

main-cart.liquid bölümünün kendisi tasarım gereği yazıktır. Sepet sayfası iskeletini işler ve {% content_for "blocks" %} aracılığıyla blok işlemesini devretir. Satır öğelerini görüntüleme ve güncelleme ağır işi cart-items-component öğesine aittir.

cart-items-component gerçekten nasıl çalışır

Horizon, React, Vue veya jQuery olmadan tamamen yerel Web Bileşenleri API'leri üzerine inşa edilmiş özel web bileşeni mimarisi kullanır. cart-items-component de dahil olmak üzere her etkileşimli bileşen, otomatik DOM referans yönetimi ve bildirimsel olay işlemesini işleyen bir temel Component sınıfını genişletir.

Tüm Horizon web bileşenleri standart Özel Öğeler yaşam döngüsünü takip eder:

• connectedCallback(), bileşen DOM'a eklendiğinde ateşlenir (ilk sunucu işlemesi)
• disconnectedCallback(), kaldırıldığında ateşlenir
• updatedCallback(), sepet mutasyonundan sonra Bölüm İşleme API'si tarafından bileşen yeniden işlendiğinde ateşlenir

Bileşenler arası iletişim için Horizon, events.js içinde bulunan ThemeEvents yardımcı programını ve türlenmiş CartUpdateEvent öğesini kullanır. Miktar değiştiğinde veya bir öğe kaldırıldığında, bileşen diğer bileşenlerin, sepet çekmecesinin, sepet simgesi rozet simgesinin, tüm özel bölümlerin dinleyebileceği bir cart:update olayını gönderir:

javascript import { ThemeEvents, CartUpdateEvent } from '@theme/events'; document.addEventListener(ThemeEvents.cartUpdate, (event) => { console.log('Sepet güncellendi:', event.detail); });

Bu olay odaklı model doğru uzantı noktasıdır. Programlı olarak öğe ekleyen özel bir "Sık Satın Alınan Birlikte" bölümü veya herhangi bir özellik oluşturuyorsanız, düzgün yapılandırılmış bir cart:update olayı gönderip sepet çekmecesi otomatik olarak açılacak ve yenilenecektir. cart-items-component öğesinin DOM'unu doğrudan manipüle etmenize gerek yoktur.

main-cart-items.liquid karışıklığı, açıklandı

Shopify'nin kendi Yardım Merkezi belgeleri, bir tarih seçici veya özel sepet alanları ekleme konusunda hâlâ tüccarları main-cart-items.liquid konusuna işaret eder. Bu Dawn'da iyi çalışır. Horizon 3.3.0 ve sonraki sürümlerde, bu dosya sections/ içinde mevcut değildir, bu da tam olarak Horizon kullanıcıları tarafından Şubat 2026 kadar yakın zamanda bildirilen hata olabilir.

İşte doğru haritalama:

Dawn (OS 2.0 deseni): Özel sepet alanları sections/main-cart-items.liquid içinde, bunları mevcut sepet formunda sarmalayarak gider.

Horizon deseni: Özel sepet alanları, tercih sırasına göre üç yerden birine aittir:

1. Yeni bir blok dosyası (blocks/my-cart-field.liquid) tüccarın yapılandırılabilir ayarlarını açığa çıkaran {% schema %} ile. Tüccarların editörde açıp kapatabilmeleri için sepet template JSON'suna ekleyin.
2. Bir snippet (snippets/my-cart-field.liquid) main-cart.liquid içinden veya bir bloktan koşullu olarak işlenir. Her zaman görünmesi gereken mantık için iyi.
3. main-cart.liquid dosyasında doğrudan düzenleme, son çare olarak, tam olarak neyin değiştirildiğini ve neden değiştirildiğini belirten açık bir yorumla, çünkü Horizon düzenli güncellemeler alır ve çekirdek dosyadaki herhangi bir değişiklik her güncellemeden sonra manuel olarak yeniden uygulanmalıdır.

Sepet özniteliği (teslimat tarihi veya hediye mesajı gibi) yakalamak için, Shopify Liquid belgelerine göre giriş name="attributes[attribute-name]" ve form="cart" taşımalıdır. Horizon'da, sepet form kimliği hâlâ cart olduğundan, HTML kendisi Dawn'la aynıdır, yalnızca düzenlediğiniz dosya değişmiştir.

Özel koddan sepet olaylarını tetikleme

Özel bölümünüz standart Shopify ürün formunun yerine AJAX Sepet API'si (/cart/add.js) aracılığıyla öğe eklerse, Horizon'un bileşenleri yanıt vermeleri için doğru olayı manuel olarak ateşlemeniz gerekir. Shopify Geliştirici Topluluğu forumlarında doğrulanan minimal çalışma deseni:

javascript document.dispatchEvent( new CustomEvent('cart:update', { bubbles: true, detail: { data: { itemCount: cart.item_count, source: 'my-custom-component' } } }) );

Alternatif olarak, özelliğiniz standart {% form 'product', product %} Liquid etiketi kullanıyorsa, bunu Horizon'un mevcut web bileşeni yapısı içine sarmalayıp, hiçbir ek JavaScript masrafı olmaksızın otomatik AJAX gönderimi ve sepet çekmecesi açılması verir.

Güncelleme güvenliği: GitHub depo gecikmesi sorunu

Bilmeniz gereken pratik bir sorun: Nisan 2026 itibariyle, Theme Store'daki Horizon teması v3.5.1 iken genel Shopify/horizon GitHub deposu yaklaşık iki ay boyunca v3.4.0 konumunda kalmıştır. Bu, depoyu Horizon değişikliklerini kendi özelleştirilmiş fork'unuza çekmek için upstream uzaktan kumanda olarak kullanırsanız, son düzeltmeleri kaçıracağınız anlamına gelir.

Güvenli iş akışı:

1. En son tema zip dosyasını doğrudan Theme Store'dan indirin.
2. main-cart.liquid ve etkilenen herhangi bir snippet'i indirilen sürümü fork'unuzun sürümüne karşı karşılaştırmak için bir diff aracı kullanın.
3. Özelleştirmelerinizi yeni taban çizgisinin üzerine yeniden uygulayın.
4. Belgelenen her değişikliği ve gelecekteki her güncellemede birleştirme sürecine sahip olmadığınız sürece main-cart.liquid veya herhangi bir çekirdek Liquid dosyasını satır içinde düzenlemeyin.

Horizon'un bloklar ve snippet'ler içindeki {% stylesheet %} ve {% javascript %} etiketi desteği (Summer 2025 başlatılmasından beri vurgulanan Liquid Storefronts özelliği), özel bloğunuzun CSS ve JS'nin bileşen başına paketlenmesi ve önbelleğe alınması anlamına gelir. Bunu theme.liquid aracılığıyla stilleri enjekte etmek yerine kullanın.

Sepet satır öğelerini güncelleme açısından güvenli bir şekilde özelleştirme

Hedefiniz her sepet satırı için işlenenin değiştirilmesi ise (özel rozetler, satır öğesi özelliği görüntüsü, paket göstergeleri), main-cart-items.liquid avcılığı yapmak yerine snippets/cart-line-item.liquid öğesini inceleyin. Bu snippet, cart-items-component öğesinin her line_item için yinelediği şeydir. Seçenekleriniz:

• Bir blok aracılığıyla geçersiz kılın: Ek işaretleme işleyen bir blocks/cart-row-badge.liquid oluşturun. Sepet template JSON aracılığıyla enjekte edin.
• Uygulama bloklarını kullanın: Üçüncü taraf bir uygulamanın sepet satırlarına kullanıcı arayüzü enjekte etmesi gerekiyorsa, uygulama blokları onaylanan yoldur. Horizon'un şeması app blok türlerini destekler ve bu yaklaşım tema güncellemeleri temiz bir şekilde hayatta kalır.
• Satır öğesi özellikleri görüntüsü: Çekirdek bölümün içinde değil, bir snippet veya blok içinde item.properties aracılığıyla döngü kurun. Shopify Liquid belgeleri, benzersiz özelliklere sahip satır öğelerinin ayrı satır öğelerine ayrıldığını doğrular, bu nedenle görüntüleme mantığınızın bu durumu işlemesi gerekir.

Horizon'un blok iç içe yerleştirmenin (Dawn'un 2'sine kıyasla 8 seviyelerine kadar) karmaşık özelleştirmeler mimarisini nasıl değiştirdiğine daha derinlemesine bakmak için, Shopify tema geliştirme rehberimi görün. Sepet sayfası performansı özelleştirme ile birlikte bir endişe ise, Shopify hız optimizasyonu dökümü, Horizon'un bileşen kapsamındaki CSS ve JS tesliminin Core Web Vitals puanlarını nasıl etkilediğini kapsar.

Özet

Horizon'un sepeti bozuk değil, yeniden tasarlanmıştır. Dawn'un main-cart-items.liquid dosyası main-cart.liquid (iskelet) artı cart-items-component (etkileşimli katman) ile değiştirilmiştir. Yeni bloklar ve snippet'ler aracılığıyla özelleştirin, cart:update olay sistemi aracılığıyla iletişim kurun ve çekirdek Liquid dosyasında yapılan herhangi bir düzenlemeyi sonraki güncellemede ödeyeceğiniz teknik borç olarak değerlendirin. Bu disiplin, altı ay içinde bir birleştirme kabusu haline gelenden bir Horizon mağazasını ölçeklendiren bir şeyi ayıran şeydir.