- القالب المخصص يستبدل عرض بلوك موجود بترميزك الخاص، ويمرر لك بيانات ذلك البلوك نفسها (عنوان Header وعدد العناصر، وإجماليات Summary، وهكذا). لا يضيف شيئًا جديدًا؛ بل يعيد تنسيق بلوك واحد.
- بلوك Custom code يضيف بلوكًا جديدًا من HTML أو React عشوائي في أي مكان في السلة.
- حدد بلوكًا في المحرر وافتح علامة تبويب Code الخاصة به.
- حرر القالب الافتراضي. القوالب المخصصة JSX فقط (خيار HTML أو JSX حصري لبلوك Custom code).
- انقر Compile. يزيل التجميع الأنواع ويحوّل JSX، فيلتقط أخطاء الصياغة. أخطاء الأنواع لا توقف التجميع — يشير المحرر إليها ضمنيًا أثناء الكتابة، بنفس IntelliSense الذي يكمل خصائص البلوك تلقائيًا.
- فعّل القالب لتستخدمه السلة بدلًا من العرض المدمج. عند تفعيل القالب، تظهر أيقونة </> خضراء بجوار البلوك في الشريط الجانبي، وتظهر نقطة خضراء نابضة على علامة التبويب Code. وتختفي كلتاهما إذا عطّلت القالب.
- يعيد Reset to default قالب البلوك الأصلي في أي وقت.
- قواعد التجميع (تعبير واحد، لا
export default، لا استيرادات) - الخصائص الدقيقة التي يستقبلها البلوك، مطابقة لما يعرضه IntelliSense في المحرر
- توقيع الدالة المقفل الذي يفرضه المحرر
- قواعد خاصة بالبلوك (تنسيقات الأموال، والمعالجات الواجب ربطها، ومتطلبات إمكانية الوصول)
- قسم للملء تلصق فيه قالبك الحالي وتصف التغيير الذي تريده
الموجه خاص بكل بلوك. لا يظهر زر Copy AI prompt إلا على البلوكات التي تدعم القوالب المخصصة.
ما تحتفظ به: موضع البلوك في السلة، ومفتاح رؤيته، وإعداداته (التي لا تزال تغذي الخصائص التي تستقبلها)، ولوحة Custom CSS الخاصة بالسلة، وهيكل التحميل المدمج.
هذا الأخير يفاجئ الناس. يتحقق البلوك مما إذا كانت السلة لا تزال تُحمَّل قبل الوصول إلى قالبك، لذا يُعرض الهيكل المدمج أثناء التحميل ولا يعمل قالبك إلا بعد جاهزية السلة. لا تحتاج إلى بناء حالة تحميل.
قالبك هو مكوّن دالة واحد. يُجمَّع من TSX، فتُسمح تعليقات الأنواع وتُزال وقت التجميع. لهذا كُتبت القوالب الافتراضية بها:
- لديك خمسة خطافات:
useStateوuseEffectوuseMemoوuseRefوuseCallback. إضافة إلىFragment، لأجل<>…</>. - لا توجد استيرادات. لا يمكنك عمل
importلأي شيء، ولا يوجد كائنReactفي النطاق، فلاReact.useReducerولاReact.Children. إذا لم يكن الخطاف في القائمة أعلاه، فهو غير متاح. - الخصائص للقراءة فقط. تعديل خاصية لن يفيد شيئًا. لتغيير السلة، استخدم خصائص المعالجات التي يمنحك إياها البلوك (
onCloseوincrementوselectPlanوغيرها) بدلًا من الكتابة في الخصائص مباشرة. windowقابل للوصول، فيمكن للقالب استدعاء Cart SDK عبرwindow.aftersell.cartعندما يحتاج شيئًا لا تغطيه خصائص البلوك.
- خصائص
*Htmlهي نص منسّق منقّى مسبقًا. اعرضها بـdangerouslySetInnerHTML. فقد مرت بالفعل عبر منقّي السلة، ورموز التاجر مثل{{total_price}}مستبدلة مسبقًا. - الأسعار التي تصل كـ
stringمنسّقة مسبقًا بتنسيق عملة المتجر. الأسعار كـnumberتكون بالسنتات. يمنحك البلوك أحدهما، وجدول كل بلوك يحدد أيهما. isLoadingدائمًاfalseداخل القالب. يعرض البلوك هيكله المدمج ولا يستدعي قالبك إلا بعد تحميل السلة، لذا تُمرَّر الخاصية للاكتمال وليس لتتفرع عليها.
بعض البلوكات لا تعرض شيئًا إطلاقًا في حالات معينة، لذا لا يُستدعى قالبك أبدًا ببيانات فارغة. قالب Rewards لا يرى أبدًا
milestones فارغة، وقالب Subscription upgrade لا يرى أبدًا view بقيمة null. يذكر مرجع كل بلوك أين ينطبق ذلك، لتتمكن من تخطي فرع الحالة الفارغة.
فـ
cart-internal-header__title هو ما يجعل العنوان يبدو كالعنوان المدمج، وcart-external-header__title هو المقبض الذي يُفترض أن تمسك به عندما تريد تغيير مظهره.
إذا كنت تعيد ترتيب العناصر أو تعيد التسمية أو تضيف شيئًا داخل البنية الحالية، فاترك أسماء الأصناف كما هي. تحتفظ بالمظهر المدمج مجانًا، وتعيد التنسيق عبر Custom CSS مستهدفًا خطافات cart-external-*.
بمجرد أن تغيّر بنية DOM بدلًا من تعديلها الطفيف، أزل كلتا العائلتين من ترميزك واستخدم أسماء أصناف خاصة بك بدلًا منهما. ولكل منهما سبب منفصل.
احذف cart-internal-* لأن CSS المدمج كُتب لبنية DOM المدمجة. إذا أبقيت تلك الأصناف على ترميز أُعيدت هيكلته، فسترث قواعد تخطيط تفترض عناصر لم تعد لديك: حاويات flex تتوقع أبناءً مختلفين، وتباعدًا بين عناصر انتقلت، وتموضعًا نسبةً إلى شيء أزلته. يظهر هذا عادة على شكل CSS الخاص بك “لا يعمل” بينما القواعد المدمجة هي الفائزة.
طريقتان لتنسيق ما بنيته:
الأفضل لأي شيء ستصونه أو تعيد استخدامه. امنح أصنافك بادئة لن يتصادم بها أحد، عادةً اسم متجرك أو علامتك التجارية:
.header أو .title معرّض للتصادم مع أصناف السلة نفسها، أو قالب تطبيق آخر، أو بلوك مستقبلي.
بلا ذهاب وإياب مع لوحة CSS، وكل شيء في مكان واحد:
:hover أو أشباه أصناف أخرى، ولا استعلامات وسائط، ولا إعادة استخدام عبر البلوكات. الجأ إلى الخيار 1 عندما تريد أيًا من ذلك.
تُعرض السلة في shadow root، لذا لا يمكن لورقة أنماط قالبك الوصول إلى داخلها. يجب أن تأتي أنماط القالب المخصص من لوحة Custom CSS الخاصة بالسلة أو من أنماط مضمّنة، وليس من قالبك. راجع CSS المخصص.
ولأن البلوك يختفي بصمت بدلًا من إظهار خطأ مرئي، افحص القالب دائمًا في المعاينة قبل النشر. إذا اختفى بلوك، فافتح وحدة تحكم المتصفح أولًا.
أمران يستحقان الحذر، لأن كليهما يُسقط قالبًا يفترض خلاف ذلك:
- الخصائص القابلة للقيمة الفارغة. كثير من الخصائص تكون
nullفي الظروف العادية (logoUrlبلا شعار، وimageUrlبلا صورة، وvariantTitleعلى منتج أحادي النسخة). تحقق قبل استخدامها. - المصفوفات التي قد تكون فارغة.
discountTagsوdiscountCodesتكونان[]في أغلب الأحيان.
- القوالب المخصصة تجاوزات عرض. لتشغيل منطق على السلة (الاشتراك في الأحداث، إضافة عناصر، التفاعل مع التغييرات)، استخدم السكربتات المخصصة وCart SDK.
- كل بلوك تقريبًا يدعم قالبًا. الاستثناءات هي بلوك Express payments الذي يستضيف أزرار دفع Shopify نفسها، وحاوية Cart items نفسها، وإن كان صف Product داخلها يدعم قالبًا مخصصًا.
- لا يمكن للقالب تغيير ما يفعله البلوك جوهريًا. فهو يغيّر طريقة عرض بيانات البلوك، وليس البيانات أو السلوك خلفها.
بلوك Custom code هو الواجهة الوحيدة التي تضيف ترميزًا بدلًا من استبدال عرض بلوك، لذا فإن خصائصه مختلفة: السلة بأكملها، إضافة إلى إجراء إضافة إلى السلة. راجع بلوكات الكود المخصص ← الخصائص.