5 Kasım 2026 · 6 dk okuma

Shopify Horizon Theme Blocks Açıklaması: content_for 'blocks', İç İçe Geçme ve Gerçek Limitler

Shopify Horizon theme blocks için kapsamlı teknik rehber: content_for 'blocks' nasıl çalışır, 8 seviyeye kadar iç içe geçme nasıl bağlanır ve her

Shopify Horizon Theme Blocks Açıklaması: content_for 'blocks', İç İçe Geçme ve Gerçek Limitler

Shopify Horizon tema sistemi, klasik {% for block in section.blocks %} döngüsünü tek bir Liquid etiketi olan {% content_for 'blocks' %} ile değiştirir ve tüm satıcı tarafından yapılandırılan blokları doğru sırada, altlarındaki her iç içe seviyesi de dahil olmak üzere işler. Tema blokları ayrılmış bir /blocks klasöründe bulunur, temadaki her bölümde yeniden kullanılabilir ve 8 seviye derine kadar iç içe geçebilir (bölümün kendisi dahil değildir). content_for'un iki varyantını ve Shopify'ın uyguladığı birkaç sabit limiti anladıktan sonra, mimari yapı tahmin edilebilir hale gelir.

Temel çıkarımlar

  • {% content_for 'blocks' %} manuel blok döngüsünü değiştirir; sıralamayı ve iç içe geçmeyi otomatik olarak yönetir.
  • Tema blokları /blocks'ta bulunur, bölümler arasında yeniden kullanılabilir ve iç içe geçmeyi destekler. Bölüm blokları iç içe geçmeyi desteklemez.
  • İç içe geçme 8 seviyeyle sınırlıdır, bölüm seviyesi hariç. Bölüm başına blok limiti 50; şablon başına 1.250'dir.
  • Bir tema, /blocks'ta en fazla 300 dosya tutabilir; hiç referans verilmemiş AI tarafından oluşturulan bloklar dahil.
  • Bölümler tema bloklarını VEYA yerel bölüm bloklarını destekleyebilir, asla ikisini birden destekleyemez.

Neden önemli: Mimari düzlemde Horizon vs. Dawn

Dawn, bölümleri dikey olarak istifleyerek sayfaları oluşturur; her biri, şemasının içinde kendi blok tanımlarına sahiptir. Bu, Online Store 2.0'ın en tam anlamıyla halidir. Horizon, bölümler ve bloklar arasındaki ilişkiyi temelden değiştirir.

Horizon 21 Mayıs 2025 tarihinde piyasaya sürüldü ve yeni tema-blok modeli üzerine tamamen inşa edilen ilk tema ailesidir. Tema 95 tema blok dosyası ile gemi; Dawn sıfırla gemi. Pratik anlamda ne demek olduğu: Horizon'da, bölüm blokları delegelendiren bir konteynerdır ve bu bloklar tek bir bölümün sahip olduğu yerine tüm tema genelinde paylaşılır.

ÖzellikBölüm blokları (Dawn modeli)Tema blokları (Horizon modeli)
Tanım yeriBir bölümün {% schema %} içinde/blocks/ klasöründe kendi dosyası
Bölümler arasında yeniden kullanılabilirHayırEvet
İç içe geçme desteklendiHayırEvet, 8 seviyeye kadar
Tarafından işlenir{% for block in section.blocks %}{% content_for 'blocks' %}
Satır içi yerel alt bloklar tanımlayabilirEvet (bölümlerde)Hayır
Ön ayarlar olmadan blok seçicide görünürEvetHayır, ön ayarlar gereklidir
300 dosya limitine doğru sayılırHayırEvet, referans verilmemiş olsa bile

Mimari fark, bir Dawn özelleştirmesini bir Horizon bölümüne taşırken otomatik bir çeviri olmadığı anlamına gelir.

content_for 'blocks' aslında nasıl çalışır

Etiketin iki farklı biçimi vardır ve bunları karıştırmak kod incelemelerinde gördüğüm en yaygın hatadır.

Form 1: tüm dinamik blokları işle

{% content_for 'blocks' %}

Bu, satıcının tema editöründe eklediği her bloğu, JSON şablonunda saklanan sırada çıktı verir. Döngü yok, {% case block.type %} yok, manuel {% render block %} yok. Platform her şeyi yönetir. Bunu hem bölümlerde hem de alt blokları kabul eden herhangi bir tema bloğunda kullanırsınız.

Form 2: tek bir statik bloğu işle

{% content_for 'block', type: 'announcement-bar', id: 'top-bar' %}

Bu, belirli bir bloğu Liquid'teki belirli bir konuma sabitlemiştir. Satıcı yine de ayarlarını yapılandırabiliyor, ancak onu taşıyamıyor veya silemiyorlar. Statik bloklar kaydedilen JSON'da "static": true taşır ve satıcılar onları yeniden sıralayamadıkları için block_order dizisinden hariç tutulur. Shopify, onların Liquid kaynağındaki konumuna bağlı olarak dinamik bloklar ile ilgili görüntüleme sırasını belirler. Ayrıca statik bloklara keyfi parametreleri iletebilirsiniz; örneğin color: "#F00", bloğun {{ color }} olarak eriştiği.

İnsanları yakalayan bir kural: {% content_for %} ile statik olarak işlenen bloklar, 50-blok-bölüm başına veya 1.250-blok-şablon başına limitine doğru sayılmaz. Yalnızca satıcı tarafından eklenebilir dinamik bloklar sayılır.

Bir bölümü tema bloklarına dahil etme

Bölüm iki şey yaparak dahil olur:

  1. Bölümün blocks dizisinde { "type": "@theme" } (ve isteğe bağlı olarak { "type": "@app" }) bildirme.
  2. Blokların işlenmesi gereken yere {% content_for 'blocks' %} yerleştirme.
{%- comment -%}
  sections/flexible.liquid
{%- endcomment -%}
<div class="flexible-section" {{ section.shopify_attributes }}>
  {% content_for 'blocks' %}
</div>

{% schema %}
{
  "name": "Flexible section",
  "blocks": [{ "type": "@theme" }, { "type": "@app" }],
  "presets": [{ "name": "Flexible section" }]
}
{% endschema %}

@theme editöre, tanımlanmış bir ön ayarı olan /blocks klasöründeki her dosyayı sunmasını söyler. @app de yüklü uygulamalardan blokları kabul etmesini söyler. @app öğesini atlarsanız, uygulama inceleme widget'ları ve benzer entegrasyonlar o bölüme basitçe enjekte edilemez.

Bir sabit kısıtlama: bölüm tema bloklarını VEYA yerel bölüm bloklarını destekleyebilir, asla ikisini birden destekleyemez. { "type": "@theme" } eklemek istediğiniz andan itibaren, bölüm tüm blok yönetimini tema-blok sistemine devreder.

İç içe geçebilen bir tema bloğu oluşturma

Bir tema bloğu alt öğeleri kabul etmesini sağlamak, tam olarak aynı desen uygulanarak bir seviye aşağıda yapılır:

{%- comment -%}
  blocks/group.liquid
{%- endcomment -%}
<div class="group" {{ block.shopify_attributes }}>
  {% content_for 'blocks' %}
</div>

{% schema %}
{
  "name": "Group",
  "blocks": [{ "type": "@theme" }, { "type": "@app" }],
  "presets": [{ "name": "Group" }]
}
{% endschema %}

{{ block.shopify_attributes }} çıktısı sarmalayıcı öğede isteğe bağlı değildir. Tema editörü, tıkla-seç davranışını bağlamak için bu veri nitelikleri kullanır. Onsuz, önizlemede bloğa tıklamak, bloğun kenar çubuğu panelini açmaz.

Tema bloklarına özgü bir kısıtlama: bölümlerin aksine, tema blokları şemasında satır içi olarak yerel bloklar tanımlayamaz. Mevcut blokları türe göre referans gösterebilirler (@theme, @app veya "slide" gibi adlandırılmış bir tür), ancak kendi şemasının içinde yeni bir blok bildiremezler. Tüm bloklar /blocks içinde ayrı dosyalar olarak bulunmalıdır.

Altçizgi ön eki: blokları seçiciden gizleme

Tema bloğunun yalnızca belirli bir üst öğenin alt öğesi olarak kullanılmasını istiyorsanız, dosya adını altçizgi ile ön ekleyin: blocks/_slide-item.liquid. Altçizgi ön eki olan bloklar, { "type": "@theme" } kullanan bir bölüm göründüğünde görünen genel blok seçicisinden hariç tutulur. Bir üst blok onları ada göre açıkça referans gösterdiğinde görünürler: { "type": "_slide-item" }. İşte Horizon, paylaşılan /blocks klasöründün esnekliğini kaybetmeden kısıtlanmış yuva desenleri nasıl oluşturur.

Sabit limitler, hepsi bir yerde

Shopify'ın resmi tema limitleri sayfası bu sayıları yayınlar:

LimitDeğer
Bölüm başına bloklar (dinamik)50 (max_blocks ile azaltılabilir)
JSON şablonu veya bölüm grubu başına bloklar1.250
Tema bloku iç içe geçme derinliği8 seviye, bölüm hariç
/blocks içinde tema blok dosyaları300 (referans verilmemiş dosyalar dahil)
JSON şablonu başına bölümler25

300 dosya tavanı, Sidekick kullanarak geliştirme sırasında blok oluşturmak için ağır kullanan Horizon mağazalarında hasara neden olur. /blocks içindeki her .liquid dosyası o limite doğru sayılır, hiç bölüm veya şablon tarafından referans verilmemiş olsa bile. Özel bloklar oluşturmak için Sidekick kullanıyorsanız, klasörü düzenli olarak denetleyin.

Yaygın hatalar ve bunlardan nasıl kaçınılır

  • Aynı bölümde bölüm bloklarını ve tema bloklarını karıştırmak. Shopify ikisini de işlemez. Bir modeli seçin ve bağlı kalın.
  • Sarmalayıcıda {{ block.shopify_attributes }} eksik. Editör tıkla-seç sessizce kırılır.
  • @app girişlerine limit ekleme. @app blok türü limit parametresini kabul etmez; şema hatasına neden olur.
  • Aşırı iç içe geçme. Sekiz seviye tavan, ancak 3. veya 4. seviyeyi aşan herhangi bir şey kenar çubuğunda satıcı için gezinmeyi zorlaştırır. Tasarım kesinlikle bunu gerektirmedikçe genel olarak seviye 5+ öğesini kod kokusu olarak ele alırım.
  • Kullanılmayan AI tarafından oluşturulan blokları göndermek. Bunlar 300 dosya limitine doğru sayılır ve /blocks klasörünü sessizce şişirir.
  • Tema bloku ön ayarlarını atlama. Şemasında tanımlanan ön ayarı olmayan bir tema bloğu blok seçicide görünmez ve bu nedenle satıcı için kod değişiklikleri olmadan erişilemez.

Blok kurulumunuzu doğrulama

Yeni bir tema bloğu veya bölümü bağladıktan sonra birkaç hızlı kontrol:

  1. Tema editörünü açın ve bloğun hedef bölüm için "Blok ekle" seçicide göründüğünü doğrulayın.
  2. Önizleme bölmesinde bloğa tıklayın ve kenar çubuğu panelinin açıldığını doğrulayın. Açılmazsa, {{ block.shopify_attributes }} eksiktir.
  3. Bloğu bir grubun içine yerleştirin ve alt bloğun doğru şekilde işlendiğini ve editör panelinin erişilebilir olduğunu doğrulayın.
  4. shopify theme check dosyasını yerel olarak çalıştırın. SchemaPresetsStaticBlocks denetimi, ön ayar statik bloğunun Liquid içinde eşleşen content_for 'block' etiketine sahip olmadığını uyarırsa, bu sessiz bir çalışma zamanı başarısızlığıdır.
  5. /blocks klasöründeki dosyaları göndermeden önce sayın: ls blocks/ | wc -l. 300'ün çok altında kalın; temizleme planınız olmadıkça.

Horizon temasının Dawn'ın sepet mimarisinden özellikle nasıl ayrıldığı hakkında daha ayrıntılı bir açıklama için, neden Horizon'da main-cart-items.liquid yok bölümüne bakın. Bu gönderide kullanılan Liquid nesneleri ve etiketleri hakkında hızlı bir referans için, Shopify Liquid referans kılavuzu, block, section ve ilgili damla özelliklerini kapsar.

Sonuç

Tema-blok sistemi gerçek bir mimari kaymadır, kozmetik güncelleme değildir. {% content_for 'blocks' %}, özel döngü mantığı olmadan yeniden kullanılabilirliği ve iç içe geçmeyi mümkün kılan mekanizmadır ve iki biçimini (tüm dinamik bloklar vs. bir sabitlenmiş statik blok) anlamak, Horizon'da önemsiz olmayan bir şey oluşturmanın ön koşuludur. Limitler gerçektir: 8 iç içe geçme seviyesi, bölüm başına 50 blok, /blocks klasöründe 300 dosya ve aynı bölümde tema blokları ile yerel bölüm blokları arasında kesin bir karşılıklı dışlama. Baştan itibaren bu kısıtlamalar içinde çalışın ve mimari yapı temiz kalır; bunların etrafında çalışmayı deneyin ve yeniden inşa gerektiren duvarlarla karşılaşırsınız.

Bu işi dışarıya vermek isterseniz, stüdyom Lintel Shopify tema geliştirme hizmeti veriyor.

shopifyliquidhorizontheme-blocksonline-store

Sıkça sorulan sorular

`{% content_for 'blocks' %}` ile `{% content_for 'block', type: ..., id: ... %}` arasındaki fark nedir?

İlk biçim, satıcının bir bölüme veya üst bloğa eklediği tüm dinamik blokları, JSON şablonunda saklanan sırada işler. İkinci biçim, Liquid kodunda belirli bir konuma sabitlenmiş tek bir statik bloğu işler; satıcılar onu yapılandırabilir ancak taşıyamaz veya silemezler.

Shopify bölümü aynı anda hem tema bloklarını hem de yerel bölüm bloklarını destekleyebilir mi?

Hayır. Bölüm bir model seçmelidir. Bölüm şeması @theme türünde bir blok içeriyorsa, tema-blok sistemini ve işleme için content_for 'blocks' öğesini kullanır. Aynı şemaya yerel blok tanımları ekleme desteklenmiyor ve çalışmayacak.

Neden tema bloğum blok seçicide görünmüyor?

Tema bloğu yalnızca şemasında en az bir ön ayar tanımlarsa seçicide görünür. Ön ayar olmadan, blok /blocks klasöründe bulunur ancak tema editöründe satıcı için görünmezdir.

Yedi yıllık Shopify, tek sayfada.

Roller, projeler, teknoloji yığını ve sertifikalar özgeçmişte.

Özgeçmiş PDF indir LinkedIn