تخطَّ إلى المحتوى
مطوّرو دكانالتوثيق
Englishتسجيل الدخول

بنية الحزمة

الملفات المطلوبة، وعقد الهيكل والكتلة، والمسارات المحجوزة، وقواعد CSS والأصول.

آخر تحديث 2 أيلول 2026قراءة 2 د
في هذه الصفحة

هذه الصفحة لمن ينظّم ملفات ثيم. في نهايتها تعرف ما هو مطلوب، وكيف يرتبط القالب بالهيكل، وما الذي يرفضه الخادم عند الدفع ولماذا.

الملفات#

المسار مطلوب الغرض
layout/theme.liquid نعم الهيكل الذي تُصيَّر داخله كل الصفحات
config/settings_schema.json نعم مخطط الإعدادات والأقسام؛ راجع مخطط الإعدادات
templates/home.liquid نعم عملياً نقطة دخول الصفحة الرئيسية؛ التصيير التجريبي عند الدفع يبدأ منها
templates/product.liquid، templates/category.liquid، templates/cart.liquid لكل صفحة تدعمها راجع القوالب
snippets/section-body.liquid إن أعلن المخطط أقساماً موزّع أجسام الأقسام؛ راجع الأقسام
snippets/*.liquid لا مقاطع تُضمَّن بالمسار الكامل
locales/ar.json وlocales/en.json موصى به جداول المرشّح t؛ راجع العربية أولاً
assets/* لا CSS وصور وخطوط
config/showcase.json لا مستند العرض والتثبيت الأول للثيمات ذات الأقسام

الامتدادات المسموحة فقط: .liquid و.json و.css و.svg و.png و.jpg و.jpeg و.webp و.woff2. أي .js أو .ts أو .html يُرفض؛ الثيم لا يشحن JavaScript إطلاقاً، والتفاعل يأتي من منصّة التشغيل عبر سمات data-dukkan-*. الحدود العددية في الحدود.

عقد الهيكل والكتلة#

يعلن الهيكل عن كتلة content ويملؤها كل قالب:

layout/theme.liquidLiquid
<!doctype html>
<html dir="{{ request.direction }}" lang="{{ request.locale }}">
<head>
  <meta charset="utf-8">
  <title>{{ store.name }}</title>
  <style>{% include 'assets/theme.css' %}</style>
</head>
<body>
  {% block content %}{% endblock %}
</body>
</html>
templates/product.liquidLiquid
{% layout 'layout/theme.liquid' %}
{% block content %}
  <h1>{{ product.name }}</h1>
  <p>{{ product.price | money }}</p>
{% endblock %}
  • لا يوجد متغير للمحتوى داخل الهيكل؛ ما خارج {% block %} في القالب لا يُصيَّر.
  • يمكن للهيكل أن يعلن عدة كتل (head، content، scripts_data) والقالب يملأ ما يشاء منها.
  • {% include %} يأخذ المسار الكامل داخل الحزمة: {% include 'snippets/product-grid.liquid' %}. لا يوجد بحث في مجلدات أو امتدادات ضمنية، ولا يُحلّ أي مسار خارج الحزمة.

المسارات والسمات المحجوزة#

  • snippets/sections.liquid محجوز للمنصّة: تحقنه المنصّة عند الدفع، ووجوده في حزمتك يُرفض. أنت تكتب snippets/section-body.liquid فقط.
  • لا تُصدر أبداً data-dukkan-section أو data-section-id= من Liquid الخاص بك؛ الغلاف مملوك للمنصّة، ويُرفض في الفحص الثابت وفي مخرجات التصيير التجريبي.
  • سمات القدرات مثل data-dukkan-add-to-cart وdata-dukkan-cart-count مسموحة؛ هي عقدك مع منصّة التشغيل.

قواعد Liquid#

يُرفض القالب عند الدفع إن احتوى على أيّ من: <script> (باستثناء <script type="application/ld+json"> لبيانات JSON-LD)، أو معالج حدث سطري (onclick=)، أو javascript:، أو data:text/html، أو <iframe>، أو المرشّح | raw. نصوص الأخطاء الحرفية في فحص الثيم.

كل مخرجات {{ }} تُهرَّب تلقائياً؛ الطريق الوحيد إلى HTML خام هو مرشّحات المنصّة التي تعلّم مخرجاتها آمنة (money، money_major، json، richtext). راجع المرشّحات.

CSS والأصول#

  • ضع الأنماط في assets/theme.css وضمّنها في <style> عبر {% include 'assets/theme.css' %}؛ تُفحص ملفات CSS كالقوالب، ويُرفض أي < داخلها (يمنع كسر وسم </style>).
  • استخدم الخصائص المنطقية (padding-inline، margin-inline-start) لا left/right؛ راجع العربية أولاً.
  • ابدأ أسماء الأصناف ببادئة ثيمك (.bz-card) كي لا تتصادم مع ثيم آخر مثبَّت في إعدادات محفوظة.
  • صور التاجر وملفاته تصل عبر asset_url وimg_url، لا بروابط مطلقة. صور الثيم المضمّنة في assets/ تُخزَّن وتُقدَّم من التخزين.

لا حسابات مالية في Liquid#

الأسعار كائنات { amount_minor, currency }. اعرضها بـ money، واستخدم product.savings وsection.products_total المحسوبين على المنصّة بدل الطرح والجمع في القالب. راجع الكائنات.