دليل المطوّر
ما تحتويه حزمة الثيم، وما يرفضه المُتحقِّق، وكيف يصل الإصدار إلى متجر.
ابدأ من هنا
أقصر طريق من لا شيء إلى قالب يقبله المراجع. كل خطوة أدناه يفحصها المدقّق نفسه، فالقالب الذي ينجح على جهازك ينجح عند التقديم.
- أنشئ الحزمة: «قالب جديد» في هذا الاستوديو، أو restro-theme init في سطر الأوامر. كلاهما يكتب الحزمة الأولى نفسها بكل ملفّاتها المطلوبة.
- اضبط الألوان في light.json وdark.json معاً. يُظهر الاستوديو أخطاء التباين أثناء الكتابة، قبل أن تقدّم شيئاً.
- عدّل المكوّنات أو أضفها: component.json يصف خصائصه، وtemplate.hbs بالمساعدات المسموحة، وstyles.css بالخصائص المنطقية.
- افحص، ثم عاين بالعربية والإنجليزية، فاتحاً وداكناً، بعرض الهاتف وسطح المكتب.
- أضف ثلاث لقطات على الأقل وقدّم. يعمل الفحص الآلي أولاً، ثم يراجع إنسانٌ ما يجتازه.
npx restro-theme init my-theme cd my-theme npx restro-theme validate # the same checks as the studio npx restro-theme dev # a live preview on your machine npx restro-theme login npx restro-theme publish # submits for review
الحزمة
الثيم هو بيان ولوحتا ألوان ومكوّن واحد أو أكثر وتخطيط لكل نوع صفحة. كل مسار أدناه ثابت: المثبِّت والمُتحقِّق وهذا الاستوديو يقرأون الأسماء نفسها.
my-theme/ ├── theme.manifest.json ├── tokens/ │ ├── light.json │ └── dark.json mandatory ├── components/ │ └── <key>/ │ ├── component.json props schema + slots + regions │ ├── template.hbs allowed helpers only │ └── styles.css sanitized and scoped on upload ├── layouts/ │ ├── <page-type>.json │ └── home.site-first.json optional: "homeMode": "site_first" — a second home page ├── assets/ ├── preview/ at least three screenshots ├── LICENSE └── CHANGELOG.md
البيان حقلاً حقلاً
يصف theme.manifest.json القالب للسوق وللمثبّت. كل حقل إلزامي والحقول المجهولة مرفوضة، فالخطأ الإملائي يصير خطأً لا إعداداً لا يفعل شيئاً بصمت.
- schemaVersion
- صيغة البيان. استعمل ما تكتبه الحزمة الأولى.
- key
- معرّف القالب الدائم: أحرف إنجليزية صغيرة وأرقام وشرطات. لا يتغيّر بعد الإصدار الأوّل.
- name
- اسم القالب في السوق، بالعربية والإنجليزية.
- description
- جملة أو جملتان لبطاقة السوق، باللغتين.
- version
- Semver، يُرفع مع كل إصدار.
- author
- من صنعه، وكيف يصل إليك صاحب المطعم.
- license
- الترخيص الذي يُقدَّم به القالب، باسمه في SPDX أو ترخيصك الخاص.
- platformCompat
- إصدارات المنصّة التي يعمل معها القالب، كنطاق semver.
- businessTypes
- أنواع الأماكن التي صُمّم لها — مطعم، مقهى، مخبز وغيرها. يرى التاجر القوالب المطابقة لنوع مكانه.
- supportedLocales
- اللغات التي يوجد بها نصّ القالب نفسه. العربية والإنجليزية إلزاميتان.
- colorModes
- يجب أن يذكر الفاتح والداكن معاً.
- defaultColorMode
- الوضع الذي يراه الزائر قبل أن يختار: فاتح أو داكن أو حسب النظام.
- pricing
- مجاني، أو بسعر لمرّة واحدة أو متكرّر.
- capabilities
- ما يطلبه القالب فوق القوالب وCSS — جافاسكربت مخصّص، موارد خارجية. وكلٌّ منها يضيف مراجعة.
- entry
- أين يجد المثبّت الرموز والمكوّنات والتخطيطات داخل الحزمة.
- presentation
- Presentation
- motion
- Motion
- content
- Content
رموز التصميم
يعرّف كل ملف ألوان كل المفاتيح أدناه، في الوضعين. يقرؤها المتجر متغيّراتِ CSS، فالمكوّن الذي يستعمل var(--color-primary) يتبع التاجر حين يعيد تلوين القالب.
الألوان
- primary
- secondary
- accent
- background
- surface
- surfaceRaised
- foreground
- foregroundMuted
- border
- success
- warning
- danger
- info
الخطوط
- headingFont
- bodyFont
- baseSize
- scale
- headingWeight
- bodyWeight
المسافات والأشكال
- radius
- containerWidth
- sectionPadding
- gap
أنماط المكوّنات
- buttonStyle
- cardStyle
- navbarStyle
- menuItemStyle
خيارات التخطيط
- headerType
- footerType
- menuLayout
- checkoutLayout
الوضعان إلزاميان
يوفّر الثيم ملفّي light.json و dark.json بالمفاتيح نفسها تمامًا. يرفض المُتحقِّق ثيمًا بوضع واحد، ويرفض ثيمًا يختلف وضعاه في مجموعة التوكنات. لا تستطيع المنصّة توليد الوضع الناقص بأمان، والزائر في الوضع الداكن على ثيم فاتح فقط يحصل على صفحة غير مقروءة.
التباين بوّابة لا نصيحة
يجب أن يبلغ نصّ المتن على كل سطح نسبة 4.5:1، والتعبئات ذات الدلالة 3:1، في الوضعين. الإخفاق خطأ يمنع التقديم. يُفحص تباين الحدود أيضًا لكنه ينبّه فقط، لأنّ دور الحدّ الواحد يغطّي إطارات الحقول والخطوط الزخرفية معًا.
| المقدّمة / الخلفية | الحدّ الأدنى | السبب |
|---|---|---|
| foreground / background | 4.5:1 | يجب أن يكون النص الأساسي مقروءًا على كل سطح يرسمه الثيم (المعيار 1.4.3). |
| foreground / surface | 4.5:1 | يجب أن يكون النص الأساسي مقروءًا على كل سطح يرسمه الثيم (المعيار 1.4.3). |
| foreground / surfaceRaised | 4.5:1 | يجب أن يكون النص الأساسي مقروءًا على كل سطح يرسمه الثيم (المعيار 1.4.3). |
| foregroundMuted / background | 4.5:1 | التسميات والأسعار والنصوص المساعدة تظل نصوصًا، والمعيار 1.4.3 لا يستثنيها. |
| foregroundMuted / surface | 4.5:1 | التسميات والأسعار والنصوص المساعدة تظل نصوصًا، والمعيار 1.4.3 لا يستثنيها. |
| foregroundMuted / surfaceRaised | 4.5:1 | التسميات والأسعار والنصوص المساعدة تظل نصوصًا، والمعيار 1.4.3 لا يستثنيها. |
| primary / background | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| primary / surface | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| secondary / background | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| secondary / surface | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| accent / background | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| accent / surface | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| success / background | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| success / surface | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| warning / background | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| warning / surface | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| danger / background | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| danger / surface | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| info / background | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| info / surface | 3:1 | يعرّف هذا الدور عنصر تحكّم أو حالة، لذا يجب أن يكون مرئيًا كعلامة لا كلون فقط (المعيار 1.4.11). |
| border / background | 3:1 · تحذير فقط | حين يرسم هذا الدور حدود حقل إدخال أو حلقة تركيز يجب أن يبلغ 3:1 (المعيار 1.4.11)؛ أما كخط فاصل رفيع فيمكن أن يبقى أقل. |
| border / surface | 3:1 · تحذير فقط | حين يرسم هذا الدور حدود حقل إدخال أو حلقة تركيز يجب أن يبلغ 3:1 (المعيار 1.4.11)؛ أما كخط فاصل رفيع فيمكن أن يبقى أقل. |
المكوّنات
المكوّن مجلّد فيه component.json وtemplate.hbs وstyles.css. يعلن الملف JSON الخصائص التي يعدّلها التاجر — وكلٌّ منها يصير أداةً في منشئ الصفحات — والمناطق التي يجوز أن يوضع فيها.
أنواع الخصائص
- string
- text
- richtext
- number
- boolean
- color
- image
- url
- select
- object
- array
المناطق
- header
- hero
- main
- sidebar
- footer
- floating
الفتحات تجعل المكوّن يحتوي مكوّنات أخرى، مع إمكان حصرها بمفاتيح وأعداد. خصائص الألوان تصل إلى القالب متغيّراتِ CSS خاصّة بالنسخة (--cmp-<prop>)، لا أنماطاً مضمّنة يحذفها المنقّي.
{
"key": "hero-banner",
"regions": ["hero"],
"props": {
"title": { "type": "string", "label": { "en": "Title", "ar": "العنوان" }, "required": true },
"image": { "type": "image", "label": { "en": "Image", "ar": "الصورة" } },
"overlay": { "type": "color", "label": { "en": "Overlay", "ar": "التظليل" } },
"align": { "type": "select", "label": { "en": "Align", "ar": "المحاذاة" },
"options": [ { "value": "start", "label": { "en": "Start", "ar": "البداية" } },
{ "value": "center", "label": { "en": "Centre", "ar": "الوسط" } } ] }
},
"slots": []
}القوالب
Handlebars بمجموعة مساعدات ثابتة ولا شيء غيرها. تُرفض الأقواس الثلاثية وصيغة العلامة & والكتل الخام لأنها تُخرج HTML بلا تهريب؛ وتُرفض الأجزاء والمزخرفات لأنّ هدفها يُحلّ وقت التصيير ولا يمكن فحصه قبل التنفيذ.
المساعدات المسموحة
- if
- unless
- each
- t
- money
- date
- img
- url
- eq
- ne
- gt
- lt
- and
- or
- not
- concat
متغيّرات البيانات المسموحة
- @index
- @key
- @first
- @last
مرفوضة بالاسم
- with
- log
- lookup
- blockHelperMissing
- helperMissing
أوراق التنسيق
يُعقَّم CSS الخاص بك ويُحصر في نسخة المكوّن قبل التخزين. تُزال import و expression() و behavior و -moz-binding؛ ولا يشير url() إلا إلى صورة data أو إلى نطاق يعلنه البيان؛ وتتحوّل position: fixed إلى absolute حتى لا يغطّي مكوّن صفحة الدفع.
استخدم الخصائص المنطقية. تعمل padding-inline و margin-inline-start بشكل صحيح في العربية والإنجليزية بقاعدة واحدة؛ أمّا padding-left فتصحّ في واحدة فقط.
جافاسكربت
إعلان capabilities.customJs يرسل الإصدار إلى مراجع بشري دائمًا. يُنفَّذ السكربت داخل إطار على أصل منفصل بلا وصول إلى المتجر: لا كوكيز ولا تخزين ولا مستند أب. ولا يصل إلى الصفحة إلا عبر مجموعة مغلقة من أوامر DOM موجّهة إلى أسماء data-ref يعلنها قالبك.
تُرفض eval ومُنشئ Function و import() و require و WebSocket والعمّال و document.cookie و localStorage وكل ما يكتب في innerHTML، بالتحليل الساكن قبل تخزين السكربت أصلًا.
من المسودّة إلى المتجر
يصبح الإصدار الذي تقدّمه مُقدَّمًا، ثم يُفحص آليًا، ثم ينتقل إلى قيد المراجعة. يقبله مراجع أو يرفضه بأسباب تقرأها في صفحة الثيم. القبول والنشر فعلان منفصلان بصلاحيتين منفصلتين، لذا ينتظر الإصدار المقبول قبل عرضه على التجّار.
لماذا تُرفض الإصدارات
يرفض الفحص الآلي الإصدار برمز يظهر في صفحة قالبك. هذه أكثرها شيوعاً، وما الذي يجب تغييره.
- TOKENS_MODE_KEY_MISMATCH
- يعرّف light.json وdark.json مفاتيح مختلفة. عرّف كل مفتاح في الملفّين.
- TOKENS_CONTRAST_FAIL
- زوج ألوان مطلوب دون حدّه الأدنى في أحد الوضعين. الجدول أعلاه يذكر كل زوج؛ عدّل الطرف الأغمق أو الأفتح.
- MANIFEST_SCHEMA
- حقل في البيان مفقود أو مكتوب خطأً أو من نوع خاطئ. الرسالة تسمّي الحقل.
- MANIFEST_PLATFORM_LOCALE_MISSING
- العربية أو الإنجليزية غير مذكورة في supportedLocales.
- HB_TRIPLE_STACHE
- قالب يستعمل {{{ }}}، التي تطبع HTML دون تهريب. استعمل {{ }} والمساعدات المتاحة.
- HB_UNKNOWN_HELPER
- قالب يستدعي مساعداً خارج القائمة المسموحة. استعمل واحداً من القائمة أعلاه.
- CSS_URL_HOST
- رابط url() يشير إلى مضيف لا يعلنه البيان. أعلنه تحت capabilities، أو ضمّن الصورة.
- CSS_POSITION_FIXED
- position: fixed يُعاد كتابته إلى absolute كي لا يغطّي شيءٌ صفحة الدفع. رتّب المكوّن من دونه.
- JS_STORAGE
- السكربت يلمس localStorage أو sessionStorage. لا تخزين لسكربتات القوالب؛ أبقِ الحالة في الصفحة.
- CHECKSUM_UNSAFE_PATH
- مسار ملفّ يخرج من الحزمة (../ أو مسار مطلق). أبقِ كل ملفّ داخل مجلّد القالب.
ما يعيده المراجع
- أقلّ من ثلاث لقطات، أو لقطات لا تُظهر القالب كما قُدِّم.
- تخطيط عربي مكسور: نصّ يجري في الاتجاه الخاطئ، أيقونات غير معكوسة، أو حشو في الجهة الخاطئة.
- صفحات تنكسر بلا قائمة أو صور أو مراجعات — والمطعم الجديد بلا الثلاثة.
- نوع صفحة بلا تخطيط، فيلجأ المثبّت فيه إلى تخطيط المنصّة الافتراضي.
- خطوط أو صور أو شيفرة مضمّنة بلا ترخيص يسمح بذلك.
الإصدارات
Semver، وملاحظات إصدار ابتداءً من الإصدار الثاني. يصل إصدار التصحيح إلى التجّار الذين فعّلوا التحديث التلقائي؛ وينتظر الإصدار الأصغر أو الأكبر قبول كل تاجر. سحب إصدار يمنع التثبيتات الجديدة دون كسر المتاجر التي تشغّله.
سطر الأوامر
يشغّل هذا الاستوديو و theme-cli المُتحقِّقات نفسها على صيغة الحزمة نفسها، فما يجتاز هنا يجتاز هناك. سطر الأوامر هو ما تريده لمستودع وخطّ أنابيب وأرشيف .rtheme موقّع؛ والاستوديو هو ما تريده للوحة الألوان والمعاينة.
الحدود
- البيان
- 64 KiB
- القالب
- 128 KiB
- ورقة التنسيق
- 256 KiB
- السكربت
- 128 KiB
- لقطات الشاشة
- من 3 إلى 12