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

ابنِ ثيماً خلال 15 دقيقة

من مجلد فارغ إلى معاينة حية على متجرك التجريبي بقالب صحيح من ملفين.

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

هذه الصفحة لمن يبني ثيماً لواجهات متاجر دكان. الثيمات قوالب Liquid تُصيَّر على خوادم دكان داخل بيئة معزولة، بلا أي JavaScript من طرف الثيم، وبنموذج بيانات عربي أولاً واتجاه RTL افتراضياً. أداتك هي @dukkan.one/theme-cli، وفي نهاية الصفحة يكون لديك ثيم يعمل في معاينة حية على متجرك التجريبي.

١. جهّز بيئتك#

تحتاج إلى Node.js 18.17 أو أحدث، وحساب مطوّر، ومتجر تجريبي نشط (أنشئه من هنا).

Shell
npx @dukkan.one/theme-cli theme init my-theme
cd my-theme
npx @dukkan.one/theme-cli login

يفتح login تدفق رمز الجهاز: يطبع رابط /cli/authorize ورمزاً بصيغة DKN-XXXXXX، تؤكّده في البوابة وتختار المتجر التجريبي الذي تعمل عليه. الرمز الناتج يصل إلى ذلك المتجر التجريبي فقط ولا يمكنه لمس أي متجر حقيقي. تفاصيل التدفق والأخطاء في مرجع الأداة.

تحذير

ينشئ theme init في الإصدار المنشور 0.1.0 ملف layout/theme.liquid بصيغة قديمة لا يدعمها محرّك التصيير، فتظهر الصفحة فارغة. استبدل الملفين كما في الخطوة الرابعة قبل أول theme dev.

٢. حلقة التطوير#

Shell
npx @dukkan.one/theme-cli theme dev

يدفع الثيم كمسودة لمتجرك التجريبي، ثم يراقب الملفات ويدفع عند كل تغيير، ويطبع رابط معاينة حية على واجهة المتجر التجريبي بصيغة https://dukkan.one/stores/YOUR_SANDBOX_SLUG?__preview=TOKEN. رابط المعاينة صالح 24 ساعة، ويُبطَل تلقائياً عند أي دفعة تغيّر المسودة، فتطبع الأداة رابطاً جديداً.

٣. بنية الثيم#

المسار الغرض
layout/theme.liquid الهيكل العام: <html> و<head> وموضع {% block content %}. مطلوب.
templates/home.liquid الصفحة الرئيسية وقائمة المنتجات ونتائج البحث.
templates/category.liquid صفحة التصنيف.
templates/product.liquid صفحة المنتج.
templates/cart.liquid السلة.
config/settings_schema.json الإعدادات التي يحرّرها التاجر في المحرّر المرئي. مطلوب.
locales/ar.json نصوص الواجهة للمرشّح t؛ locales/en.json اختياري.
snippets/*.liquid مقاطع تُضمَّن بالمسار الكامل.
assets/*.css والصور CSS وصور وخطوط woff2 فقط؛ لا JavaScript إطلاقاً.

صفحات الدفع والطلبات مملوكة للمنصّة ولا تُثيَّم أبداً. الأسعار تصلك ككائن { amount_minor, currency } وتُعرض بالمرشّح money. الجدول الكامل للقواعد في بنية الحزمة.

٤. الزوج الأدنى الصحيح#

يعلن الهيكل عن كتلة content، ويعلن كل قالب أنه يُصيَّر داخل الهيكل ويملأ الكتلة:

layout/theme.liquidLiquid
<!doctype html>
<html dir="{{ request.direction }}" lang="{{ request.locale }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ store.name }}</title>
  <style>{% include 'assets/theme.css' %}</style>
</head>
<body>
  <header><a href="{{ store.url }}">{{ store.name }}</a></header>
  {% block content %}{% endblock %}
  <footer>{{ 'footer.powered_by' | t }}</footer>
</body>
</html>
templates/home.liquidLiquid
{% layout 'layout/theme.liquid' %}
{% block content %}
<main>
  <h1>{{ store.name }}</h1>
  <ul>
    {% for product in products %}
    <li>
      <a href="{{ product.url }}">{{ product.name }}</a>
      <span>{{ product.price | money }}</span>
      {% unless product.available %}<em>{{ 'product.sold_out' | t }}</em>{% endunless %}
    </li>
    {% endfor %}
  </ul>
</main>
{% endblock %}

لا يوجد متغير للمحتوى داخل الهيكل؛ العقد هو {% layout %} و{% block %} حصراً، كما في كل ثيمات دكان الأولى. النصوص العربية لا تُكتب في القوالب بل في locales/ar.json:

locales-ar.jsonJSON
{
  "nav": {
    "home": "الرئيسية",
    "cart": "السلة"
  },
  "product": {
    "add_to_cart": "أضف إلى السلة",
    "sold_out": "نفد المخزون"
  },
  "footer": {
    "powered_by": "مدعوم من دكان"
  }
}

٥. افحص#

Shell
npx @dukkan.one/theme-cli theme check
npx @dukkan.one/theme-cli theme check --remote

يطبّق theme check محلياً الشيفرة نفسها التي يطبّقها الخادم عند الدفع: قائمة الامتدادات المسموحة، وحدود الحجم والعدد، وسلامة المسارات، وصحة settings_schema.json، ومنع أي <script>. يضيف --remote تصييراً تجريبياً في بيئة الخادم المعزولة. رمز الخروج 1 عند أي خطأ، فالأمر جاهز لأنظمة CI. قائمة القواعد بنصوص أخطائها الحرفية في فحص الثيم.

الخطوة التالية#