Shopify Liquid: Tüccarlara ve Geliştiricilere Yönelik Kapsamlı Referans

Shopify Liquid, her Shopify mağazasını destekleyen açık kaynaklı şablonlama dilidir. Mağazanızın arka uç verilerini (ürünler, koleksiyonlar, sepet, müşteri) alıcılarının gördüğü HTML'ye bağlamak için üç temel öğe kullanır: nesneler, etiketler ve filtreler. Bu üç şeyi doğru yapmak, dönüşüm yapan bir tema ile aylık olarak uygulama abonelikleri ve geliştirici biletlerinize para harcatan bir tema arasındaki farkı yaratır.

Temel noktalar

• Liquid'in üç temel öğesi nesneler {{ }}, etiketler {% %} ve filtreler | şeklindedir. Bir Shopify temasında yaptığınız her özelleştirme bu üç öğeden geçer.
• {% render %} etiketi 2019'da {% include %}'ın yerine geçmiş ve Online Store 2.0'ın desteklediği tek dahil etme etiketidir. İkisini değiştirmek eski temalar için hala en hızlı performans kazancıdır.
• 2025-2026'da eklenen yeni filtreler arasında fetchpriority ve sizes öznitelikleri içeren image_tag ve yapılandırılmış metafield sunumu için metafield_tag bulunur.
• İç içe geçmiş etiket kontrolleri içeren tek optimize edilmemiş koleksiyon döngüsü LCP'ye 2-4 saniye ekleyebilir ve saniye başına mobil gelirin yaklaşık %7'sine mal olur.
• 3-5 orta seviye uygulamayı yerel Liquid bölümleriyle değiştirmek genellikle aylık 100-300 dolar tasarruf sağlar ve sayfa başına 150-600 KB üçüncü taraf JavaScript'i kaldırır.

Shopify Liquid nedir?

Liquid, statik içeriği barındırmak için tek bir şablon oluşturmanıza ve ne gösterileceğine bağlı olarak dinamik olarak bilgi eklemenize olanak tanıyan bir şablonlama dilidir. Örneğin bir ürün şablonu tüm standart ürün özniteliklerini içerir ve her ürün URL'si için doğru içeriği dinamik olarak değiştirir.

Shopify'ın Liquid sürümü açık kaynaklı sürümü mağaza özel nesnelerle (product, collection, cart, customer, shop) ve ticaret için geliştirilmiş filtrelerle genişletir (money, image_url, metafield_tag). 13 Ocak 2026 itibariyle, Shopify ayrıca Liquid kodunu içsel olarak işleme şeklini güncelleştirerek tema işlemesini daha güvenilir hale getirdi, tüccarlardan herhangi bir işlem yapılması gerekmeksizin.

Üç temel öğe

1. Nesneler

Nesneler çift süslü parantez kullanarak dinamik verileri çıktı verir:

{{ product.title }}
{{ product.price | money }}
{{ shop.name }}

Her tema yapılandırmasında kullanacağınız anahtar küresel nesneler:

Nesneler tek bir değeri temsil edebilir veya birden fazla özelliği açığa koyabilir. request nesnesi sayfa türüne dayalı koşullu işleme için özellikle faydalıdır.

2. Etiketler

{% %} söz dizimini kullanarak etiketler mantık ve akış kontrolü ekler. Bilmeniz gereken kategoriler:

Akış kontrolü liquid {% if product.available %} <button>Sepete ekle</button> {% else %} <button disabled>Satıldı</button> {% endif %}

Yineleme liquid {% for product in collection.products limit: 24 %} {% render 'product-card', product: product %} {% endfor %}

Değişken atama liquid {% assign sale_price = product.compare_at_price | minus: product.price %} {% capture button_label %}{{ product.title }} Ekle{% endcapture %}

Tema etiketleri (bölümler, parçacıklar, düzenler) liquid {% render 'product-card', product: product, show_vendor: true %} {% section 'announcement-bar' %} {% layout 'checkout' %}

3. Filtreler

Filtreler boru karakterini | kullanarak çıktıyı değiştirir. Birden fazla filtre soldan sağa zincirlenmiş durumda:

{{ product.title | upcase | truncate: 50 }}
{{ product.price | money }}
{{ product.featured_image | image_url: width: 800 | image_tag: loading: 'lazy', widths: '200,400,600,800' }}

Kritik filtre kategorileri:

• Para filtreleri: | money, | money_with_currency, | money_without_trailing_zeros. Para birimi sembollerini asla kodla yazılı olarak sabitlenmeyiniz. | money filtresi mağazanızın para birimini, yerel ayarını ve biçimlendirme ayarlarını dikkate alır. Kodla yazılı bir $ sembolü Shopify Markets'te çoklu para birimini etkinleştirdiğiniz anda bozulur.
• Görüntü filtreleri: | image_url: width: X ardından | image_tag. Modern image_url ve image_tag filtreleri eski img_url ve img_tag'ı değiştirmiş ve tek bir zincirde doğru srcset, sizes, tembel yükleme ve fetchpriority öznitelikleri içeren yanıt veren görüntüler sunar.
• Dizi filtreleri: | where, | map, | sort, | uniq, | join, | concat. Döngüler olmadan dizileri filtrelemek için | where kullanın.
• Dize filtreleri: | upcase, | downcase, | truncate, | strip_html, | escape, | split.
• Matematiksel filtreler: | plus, | minus, | times, | divided_by, | ceil, | floor, | round.
• Renk filtreleri: | color_lighten, | color_darken, | color_mix, | color_contrast. color_contrast filtresi iki renk arasındaki kontrast oranını döndürür; bu da erişilebilir rozet ve düğme tasarımı için gereklidir.
• Yerelleştirme filtreleri: | t (çeviri), | format_address, | currency_selector.

| where tuzağı hakkında bir not: filtre büyük/küçük harfe duyarlıdır. | where: 'tags', 'Sale' 'sale' etiketini eşleştirmeyecektir. Karşılaştırmadan önce | downcase kullanın.

Bölümler ve {% schema %} etiketi

Online Store 2.0, bölümleri yalnızca ana sayfa değil, her yerde kullanılabilir hale getirmiştir. Oluşturduğunuz her bölümün, tüccarlar bir kod dosyası açmadan tema düzenleyicisinden içeriği düzenleyebilmesi için tam bir {% schema %} bloğu olmalıdır.

Her bölümün yalnızca tek bir {% schema %} etiketi olabilir; bu, geçerli JSON içermelidir. Birden fazla olması veya bunu başka bir Liquid etiketi içinde iç içe yerleştirmesi söz dizimi hatasına neden olur.

Minimal ancak eksiksiz bir bölüm şeması:

{% schema %}
{
  "name": "Feature banner",
  "tag": "section",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Our promise"
    },
    {
      "type": "image_picker",
      "id": "image",
      "label": "Background image"
    }
  ],
  "blocks": [
    {
      "type": "feature",
      "name": "Feature item",
      "settings": [
        { "type": "text", "id": "feature_text", "label": "Feature", "default": "Free shipping" }
      ]
    }
  ],
  "max_blocks": 4,
  "presets": [{ "name": "Feature banner" }]
}
{% endschema %}

Kritik kural: ayar id değerlerini veritabanı sütun adları gibi düşünün. Bunlar, bölümünüzü yükleyen her mağazanın şablon JSON'unda kalıcı anahtarlar haline gelir. Bir id'yi yeniden adlandırmak mevcut değerleri yetim bırakır. Bir text ayarını image_picker'a değiştirmek verileri geçirmez. Bölümler büyüdüğünde önek kullanın: heading yerine hero_heading kullanın, bloklarda card_heading varsa.

Ön ayarlara sahip bölümler statik olarak işlenmemelidir. Statik olarak işlenen bölümler tüccarlar tarafından kaldırılamaz veya yeniden sıralanamaz.

{% render %} etiketi (ve {% include %} neden ölü)

{% render %} etiketi, modern Shopify temalarında parçacıkları dahil etmenin tek yoludur. {% include %} parçacıklar arasında değişken kapsamını paylaştığından bu, adlandırma çakışmalarına neden olur ve performans profilini güvenilmez hale getirir. {% render %} izole bir kapsam oluşturur: parçacıklar adlandırılmış parametreler olarak aktarılmadığı sürece ana değişkenleri okuyamaz.

{# DEPRECATED - shares parent scope #}
{% include 'product-card' %}

{# CORRECT - isolated scope, explicit inputs #}
{% render 'product-card', product: product, show_vendor: true %}

{# Loop form #}
{% render 'product-card' for collection.products as product %}

İzole kapsam, parçacıkların ürün ayrıntı sayfaları, arama sonuçları, AJAX sepet yanıtları ve Bölüm Işleme API'si istekleri arasında sıfır yeniden yazımla güvenle yeniden kullanılabileceği anlamına gelir. {% include %}'ı {% render %} ile değiştirmek ayrıca Shopify Tema Mağazası gönderimini engelleyen her Tema Kontrolü hatasını temizler.

Liquid'te Metafield'ler

Metafield'ler, uygulamalara ihtiyaç duymadan Shopify'ın veri modelini özel verilerle genişletmenize olanak tanır (boyut şemaları, malzemeler, bakım talimatları, özellikleri). Liquid geliştirmesi için en güçlü metafield türleri şunlardır:

• JSON yapılandırılmış veriler için (| metafield_tag ile işleyin veya değeri ayrıştırın)
• Zengin metin tüccar tarafından düzenlenebilir HTML gövde kopyası için
• Dosya referansı ürünlere bağlı görseller ve videolar için
• Ürün/koleksiyon referansı kaynaklar arasında açık ilişkiler için

Erişim deseni:

{% assign size_chart = product.metafields.custom.size_chart %}
{% if size_chart != blank %}
  {{ size_chart.value | metafield_tag }}
{% endif %}

!= blank koruması vazgeçilmez. Bunu atlayın ve boyut şeması olmayan ürünler mobil Safari'de düzeni çöken boş bir <table> işlenir.

Metafield tanımlarını her zaman API aracılığıyla anında değil, Shopify yöneticisinin Ayarlar > Özel veriler bölümünden oluşturun. Tanımlar size tür doğrulaması, tüccar dostu etiketler ve yönetici görünürlüğü sağlar. Yotpo ve Klaviyo gibi üçüncü taraf uygulamalar bu tanımları okur, bu nedenle temiz bir şema yığının geri kalanını besler.

Gerçekten önemli performans desenleri

Döngü optimizasyonu

İç içe geçmiş döngüler, denetlediğim Liquid temalarında en yaygın performans katilidir. 50 ürün üzerinden bir dış döngü, ürün başına 20 etiketle birlikte bir iç döngüyle 1.000 yineleme boyunca sayfa işlemesinde çalışır. Bunun yerine contains operatörünü kullanın:

{# BAD: O(n*m) - 50 products x 20 tags = 1,000 iterations #}
{% for product in collection.products %}
  {% for tag in product.tags %}
    {% if tag == 'featured' %}...{% endif %}
  {% endfor %}
{% endfor %}

{# GOOD: one pass, contains check is O(1) #}
{% for product in collection.products limit: 24 %}
  {% if product.tags contains 'featured' %}...{% endif %}
{% endfor %}

Her zaman koleksiyon döngülerine limit: ekleyin. Tek optimize edilmemiş döngü mobilde LCP'ye 2-4 saniye ekleyebilir.

Görüntü işleme

{# BAD: no dimensions, no srcset, browser cannot reserve space (CLS) #}
<img src="{{ product.featured_image | img_url: 'master' }}">

{# GOOD: srcset, lazy loading, explicit width hint #}
{{ product.featured_image
  | image_url: width: 800
  | image_tag:
      loading: 'lazy',
      widths: '200,400,600,800',
      sizes: '(min-width: 768px) 400px, 100vw',
      alt: product.title }}

image_tag filtresi, daha önce manuel srcset yapısı gerektiren üç satır HTML'yi tek satırda yapar.

Boşluk kontrolü

Liquid her etiketi çevreleyen boşluğu çıktı verir. Büyük şablonlarda bu HTML'yi şişirir ve TTFB'yi yavaşlatır. Bunu çıkarmak için - değiştiricisini kullanın:

{%- for product in collection.products -%}
  {{- product.title -}}
{%- endfor -%}

Bölüm İşleme API'si

Bölüm İşleme API'si, bölümlerin AJAX aracılığıyla bağımsız olarak işlenmesine olanak tanıyarak, tam sayfa yeniden yüklenmeden daha hızlı sayfa geçişleri ve dinamik sepet güncellemeleri sağlar. Bu, başlıksız olmak zorunda kalmadan standart Liquid temalar içinde uygulamaya benzer deneyimlerin temelini oluşturur.

Tema Kontrolü ve araçlar

Tema Kontrolü 2.0 artık Shopify CLI'ye yerleştirilmiş ve dağıtmadan önce performans sorunlarını, erişilebilirlik sorunlarını ve kullanımdan kaldırılmış desen kullanımını yakalar. Her taahhütte çalıştırın. Şunları işaretler:

• {% include %} çağrıları (kullanımdan kaldırıldı)
• Görüntü etiketlerinde eksik alt öznitelikleri
• img_url kullanımı (image_url ile değiştirilmiştir)
• Döngüler limit: olmadan
• theme.liquid'te eksik content_for_header

Tema Denetçi yer paylaşımı, Liquid işleme sürelerini doğrudan mağazanızda gösterir, böylece optimize etmeden önce hangi bölümlerin, parçacıkların ve döngülerin yavaş olduğunu görebilirsiniz.

2026 itibariyle, Shopify'ın Dev MCP ayrıca AI aracılarının doğrulanmış Liquid kodu oluşturmasına ve bölüm şemalarını iskelelemesine izin verir; bu, ortak işleri hızlandırır. AI çıktısını bir taslak olarak düşünün ve her zaman Shopify'ya özgü uç durumlar için gözden geçirin.

Uygulama değişikliği: Liquid'in yerel olarak yapabilecekleri

Tema başına 3-5 uygulamayı yerel Liquid bölümleriyle değiştirmek genellikle aylık 100-300 dolar tasarruf sağlar ve sayfa başına 150-600 KB üçüncü taraf JavaScript'i kaldırır. Uygulama şişkinliği mobilde üçüncü taraf betik başına 40-200 ms'ye mal olur; bu da Lighthouse mobil puanlarını 80'den 60'a düşüren tam aralıktır.

Liquid'in yerel olarak işlediği işlevler (uygulama gerekmez):

• Geri sayım bantları şema kontrolüne sahip bitiş tarihleriyle
• SSS akordiyon soru başına blok mimarisiyle
• Tavsiye ızgaralar yıldız derecelendirmeleri ve metafield saklı incelemelerle
• Yapışkan sepete ekle çubuklar IntersectionObserver artı bir Liquid ürün bölümüyle
• Özellik karşılaştırma tabloları JSON metafield'ler kullanarak
• Önce/sonra görüntü kaydırıcıları vanilya JS ve iki görüntü seçici ayarıyla

Bölümler uygulamalardan üç eksen üstün olur: boyamadan önce işlenirler (düzen değişimi yok), tema havuzunuzda yaşarlar (sürüm kontrolü trivyaldir) ve tüccarlar geliştirici olmadan içeriği düzenleyebilmesi için şema ayarlarını açığa koydukları.

Liquid ve Hydrogen: dürüst cevap

Liquid, muasır olanların büyük çoğunluğu için doğru seçim olmaya devam eder çünkü daha hızlı geliştirme, daha düşük bakım maliyetleri ve Shopify'ın CDN'sine ve barındırma altyapısına tam erişim sağlar. Başlıksız (Hydrogen/Oxygen) yalnızca adanmış ön uç mühendislik ekiplerine ve karmaşık çok mağaza mimarilerine sahip markalar için mantıklıdır.

Adanmış bir ön uç takımınız, arka uçu paylaşan üç veya daha fazla mağazanız veya Liquid'in gerçekten ulaşamayacağı bir etkileşim modeliniz olduğunda başlıksız olmaya gidin. Başkaları için, soru "Liquid mi yoksa Hydrogen mı" değil "iki yıl sonra beni utandırmayan Liquid'i nasıl yazarım" olabilir.

Bir tema denetleme veya bu standartlara göre bir tema oluşturmada yardıma ihtiyacınız varsa, Shopify tema geliştirici hizmetleri sayfasına bakın veya performans belirli darboğaz ise Shopify hız optimizasyonunu keşfedin.

Hızlı referans kopya kağıdı

Çıktı söz dizimi

{{ product.title }}              {# string output #}
{{ product.price | money }}      {# filtered output #}
{{- product.title -}}            {# whitespace stripped #}

Akış kontrolü

{% if %} / {% elsif %} / {% else %} / {% endif %}
{% unless %} / {% endunless %}
{% case product.type %}{% when 'Apparel' %}...{% endcase %}

Döngüler

{% for item in array limit: 24 offset: 0 %}
  {{ forloop.index }} of {{ forloop.length }}
{% else %}
  No items found.
{% endfor %}

En çok kullanılan filtreler bir bakışta

| money               {# currency-safe price output #}
| image_url: width: X {# CDN-resized image URL #}
| image_tag           {# full responsive <img> tag #}
| metafield_tag       {# renders metafield value with correct HTML #}
| where: 'key', val   {# filter array without a loop #}
| map: 'property'     {# pluck a property from array of objects #}
| json                {# safe JSON output for script tags #}
| t                   {# translation key lookup #}
| handleize          {# string to URL-safe handle #}
| date: '%B %d, %Y'  {# formatted date output #}

Resmi Liquid referansını bu gönderiyle birlikte yer işareti olarak koyun. Resmi belgeler tam olarak her nesne özelliğini ve filtre parametresini kapsamaktadır.