مواصفة settings_schema.json

كل مفتاح في المخطط، وأنواع الإعدادات وقواعد قيمها، ومستند الإعدادات المحفوظ.

آخر تحديث 2 أيلول 2026قراءة 3 د

في هذه الصفحة

البنية العليا
المجموعات
تعريف الإعداد
الأنواع
تعريف القسم
مستند الإعدادات
التغييرات الإضافية فقط

هذه الصفحة مرجع لمن يكتب مخطط إعدادات ثيم. المخطط ملف JSON مطلوب يُتحقّق منه عند الدفع بأنواع مسموحة فقط وحدود صارمة، ثم تُتحقّق إعدادات التاجر ضدّه عند كل حفظ وعند النشر.

البنية العليا#

المفتاح	النوع	القاعدة
`schema_version`	عدد	يجب أن يكون `1`
`groups`	مصفوفة	مجموعات الإعدادات العامة؛ حتى 30 مجموعة
`sections`	مصفوفة	أنواع الأقسام؛ حتى 40 نوعاً

لا تُقبل مفاتيح إضافية في أي مستوى (strict). مثال أدنى:

settings-schema-minimal.jsonJSON

{
  "schema_version": 1,
  "groups": [
    {
      "id": "colors",
      "label": "الألوان",
      "settings": [
        {
          "id": "primary",
          "type": "color",
          "label": "اللون الأساسي",
          "default": "#0e7b5c"
        }
      ]
    }
  ],
  "sections": []
}

المجموعات#

المفتاح	القاعدة
`id`	`[a-z0-9_]+`، حتى 64 حرفاً، فريد بين المجموعات
`label`	1–200 حرف، يظهر للتاجر
`settings`	حتى 60 إعداداً؛ معرّفاتها فريدة عبر كل المجموعات لأنها تصبح مفاتيح مسطّحة في `theme_settings`

المعرّفات pages وtranslations و__proto__ وconstructor وprototype محجوزة ولا تُقبل كمعرّف إعداد عام.

تعريف الإعداد#

المفتاح	القاعدة
`id`	`[a-z0-9_]+`، حتى 64 حرفاً
`type`	من الأنواع
`label`	1–200 حرف
`info`	اختياري، حتى 200 حرف، يظهر تحت الحقل
`default`	نص (حتى 5,000 حرف) أو عدد أو قيمة منطقية أو `null`؛ يجب أن يطابق النوع
`options`	لـ`select` فقط؛ 1–50 خياراً `{ value, label, font? }`
`min`، `max`، `step`	لـ`number` و`range`؛ `min ≤ max` و`step > 0`
`source`	لـ`product` و`category`؛ `true` يجعل الإعداد مصدر منتجات للقسم
`localized`	لـ`text` و`textarea` و`richtext`؛ يسمح بترجمة إنجليزية في جدول `translations`

الأنواع#

النوع	القيمة المقبولة	ملاحظات
`text`	نص حتى 5,000 حرف
`textarea`	نص حتى 5,000 حرف
`richtext`	نص يُعقَّم عند الحفظ وعند التصيير إلى `p`، `br`، `strong`، `em`، `u`، `s`، `ul`، `ol`، `li`، `h2`، `h3`، `blockquote`، `a`	يُعرض بالمرشّح `richtext` حصراً
`number`	عدد منتهٍ ضمن `min`/`max`
`range`	عدد ضمن `min`/`max`	يُعرض كشريط تمرير
`checkbox`	`true`/`false`
`select`	إحدى `options[].value`	`font` اختياري على الخيار لمعاينة الخط في المحرّر فقط
`color`	`#rrggbb` بالضبط	لا `rgb()` ولا أسماء
`url`	`https://…` أو مسار مطلق على المضيف نفسه `/…`	تُرفض `//` و`/\`
`image`	مرجع ملف مخزّن في مكتبة الوسائط	يُحوَّل إلى رابط بـ `asset_url`/`img_url`
`video`	مرجع ملف مخزّن	كـ`image`
`tel`	رقم هاتف: أرقام مع `+` اختيارية	الروابط عبر `tel_href`/`wa_href` فقط
`youtube_id`	معرّف فيديو من 11 حرفاً	الثيم يبني رابطاً أو صورة مصغّرة، لا `<iframe>`
`product`	معرّف منتج في المتجر نفسه	مع `source: true` تُجلب منتجاته
`category`	معرّف تصنيف في المتجر نفسه	مع `source: true` تُجلب منتجاته
`datetime`	لحظة ISO-8601	القيم غير القابلة للقراءة تُسقط بصمت؛ `""` افتراضي مقبول

نصوص أخطاء القيم (مثل "x" must be a #rrggbb color) هي ما يراه التاجر في المحرّر؛ قائمة أخطاء المخطط عند الدفع في فحص الثيم.

تعريف القسم#

المفتاح	القاعدة
`type`	`[a-z0-9_]+`، فريد بين الأقسام
`label`	1–200 حرف
`info`	اختياري؛ وصف من سطر في مكتبة الأقسام
`category`	اختياري؛ عنوان التجميع في المكتبة (مثل «بانرات»)
`required`	اختياري؛ لا يستطيع التاجر حذفه ويُحقن تلقائياً بافتراضياته
`band`	اختياري؛ شريط بعرض الصفحة يُستثنى من التناوب
`enabled_on`	اختياري؛ 1–4 من `home`، `product`، `category`، `cart` دون تكرار؛ غيابه = الرئيسية فقط
`settings`	حتى 60 إعداداً
`blocks`	حتى 20 نوع كتلة `{ type, label, settings }` بأنواع فريدة داخل القسم

مثال يعلن قسمين:

settings-schema-sections.jsonJSON

{
  "schema_version": 1,
  "groups": [
    {
      "id": "look",
      "label": "المظهر",
      "settings": [
        {
          "id": "arabic_numerals",
          "type": "checkbox",
          "label": "أرقام مشرقية في الأسعار",
          "default": false
        }
      ]
    }
  ],
  "sections": [
    {
      "type": "hero_banner",
      "label": "بانر رئيسي",
      "info": "صورة عريضة مع عنوان وزر",
      "category": "بانرات",
      "band": true,
      "enabled_on": [
        "home",
        "category"
      ],
      "settings": [
        {
          "id": "heading",
          "type": "text",
          "label": "العنوان",
          "default": "",
          "localized": true
        },
        {
          "id": "image",
          "type": "image",
          "label": "الصورة"
        },
        {
          "id": "link",
          "type": "url",
          "label": "الرابط",
          "default": ""
        }
      ],
      "blocks": []
    },
    {
      "type": "featured_products",
      "label": "منتجات مختارة",
      "settings": [
        {
          "id": "title",
          "type": "text",
          "label": "العنوان",
          "default": "",
          "localized": true
        },
        {
          "id": "source_category",
          "type": "category",
          "label": "التصنيف",
          "source": true,
          "default": ""
        },
        {
          "id": "count",
          "type": "range",
          "label": "عدد المنتجات",
          "min": 4,
          "max": 12,
          "step": 4,
          "default": 8
        }
      ],
      "blocks": []
    }
  ]
}

مستند الإعدادات#

هذا ما يُخزَّن لكل تثبيت ويصل إلى الثيم كـ theme_settings (الإعدادات العامة مسطّحة) وpage_sections (المثيلات المحلولة):

settings-document.jsonJSON

{
  "primary": "#0e7b5c",
  "arabic_numerals": false,
  "pages": {
    "home": {
      "sections": {
        "hero_1": {
          "type": "hero_banner",
          "settings": {
            "heading": "تخفيضات الصيف",
            "image": "files/hero.jpg",
            "link": "/stores/demo/c/summer"
          }
        },
        "rail_1": {
          "type": "featured_products",
          "hidden": false,
          "settings": {
            "title": "الأكثر مبيعاً",
            "source_category": "",
            "count": 8
          }
        }
      },
      "order": [
        "hero_1",
        "rail_1"
      ]
    }
  },
  "translations": {
    "en": {
      "hero_1:heading": "Summer sale",
      "rail_1:title": "Best sellers"
    }
  }
}

الإعدادات العامة مفاتيح مسطّحة في المستوى الأعلى؛ لهذا pages وtranslations محجوزان.
pages.<page>.sections خريطة من معرّف المثيل إلى { type, hidden?, settings, blocks?, block_order? }، وpages.<page>.order ترتيب المعرّفات. حتى 30 مثيلاً لكل صفحة.
translations.en جدول ترجمات إنجليزية للإعدادات localized بمفاتيح global:<id> أو <sectionId>:<key> أو <sectionId>:<blockId>:<key>؛ حتى 300 مدخل. العربية تبقى القيمة الأساسية المخزّنة والمفاتيح غير القابلة للحل تُسقط بصمت.
قواعد التعارض: مثيل بنوع لم يعد المخطط يعلنه يُسقط بصمت؛ قيمة غير صالحة لنوع معلَن خطأ صريح؛ order يشير إلى معرّف مجهول أو يكرّره خطأ؛ الأقسام required تُحقن عند غيابها.

التغييرات الإضافية فقط#

عقد المخطط إضافي: تحديث ثيمك قد يضيف إعدادات (تأخذ افتراضياتها) أو أقساماً، ويمكنه تضييق enabled_on أو حذف نوع (تُسقط مثيلاته). لا تغيّر نوع إعداد موجود؛ أعطه معرّفاً جديداً.