Skip to main content
يتيح لك القالب المخصص تجاوز طريقة عرض بلوك بعينه. فبدلًا من واجهة البلوك المدمجة، تعرض السلة كود JSX الخاص بك، باستخدام البيانات نفسها التي كان البلوك سيستخدمها عادة. وهو قدرة شاملة وليس بلوكًا بذاته: معظم البلوكات تتيحه من علامة تبويب Code الخاصة بها. تغطي هذه الصفحة ما ينطبق على كل البلوكات. للخصائص التي يمررها لك بلوك محدد، انتقل إلى مرجع البلوك نفسه.

​
القالب المخصص مقابل بلوك الكود المخصص

يبدوان متشابهين لكنهما يفعلان أمرين مختلفين:
  • القالب المخصص يستبدل عرض بلوك موجود بترميزك الخاص، ويمرر لك بيانات ذلك البلوك نفسها (عنوان Header وعدد العناصر، وإجماليات Summary، وهكذا). لا يضيف شيئًا جديدًا؛ بل يعيد تنسيق بلوك واحد.
  • بلوك Custom code يضيف بلوكًا جديدًا من HTML أو React عشوائي في أي مكان في السلة.
الجأ إلى القالب المخصص عندما يكون البلوك المدمج قريبًا مما تريد لكنك تحتاج تخطيطًا أو ترميزًا مختلفًا. والجأ إلى بلوك Custom code عندما تريد إضافة شيء لا تغطيه البلوكات المدمجة.

​
استخدام قالب مخصص

  1. حدد بلوكًا في المحرر وافتح علامة تبويب Code الخاصة به.
  2. حرر القالب الافتراضي. القوالب المخصصة JSX فقط (خيار HTML أو JSX حصري لبلوك Custom code).
  3. انقر Compile. يزيل التجميع الأنواع ويحوّل JSX، فيلتقط أخطاء الصياغة. أخطاء الأنواع لا توقف التجميع — يشير المحرر إليها ضمنيًا أثناء الكتابة، بنفس IntelliSense الذي يكمل خصائص البلوك تلقائيًا.
  4. فعّل القالب لتستخدمه السلة بدلًا من العرض المدمج.
  5. يعيد Reset to default قالب البلوك الأصلي في أي وقت.

​
كتابة قالب بالذكاء الاصطناعي

تتضمن علامة تبويب Code زر Copy AI prompt (أيقونة العصا ✦). النقر عليه ينسخ إلى حافظتك موجزًا مكتفيًا بذاته يمكنك لصقه مباشرة في جلسة محادثة ذكاء اصطناعي (Claude أو ChatGPT أو ما شابه). يتضمن الموجه كل ما يحتاجه الذكاء الاصطناعي لكتابة قالب صالح لذلك البلوك تحديدًا:
  • قواعد التجميع (تعبير واحد، لا export default، لا استيرادات)
  • الخصائص الدقيقة التي يستقبلها البلوك، مطابقة لما يعرضه IntelliSense في المحرر
  • توقيع الدالة المقفل الذي يفرضه المحرر
  • قواعد خاصة بالبلوك (تنسيقات الأموال، والمعالجات الواجب ربطها، ومتطلبات إمكانية الوصول)
  • قسم للملء تلصق فيه قالبك الحالي وتصف التغيير الذي تريده
بعد النسخ، افتح جلسة ذكاء اصطناعي، والصق الموجه، واملأ الفراغين في الأسفل (قالبك الحالي والتغيير الذي تريده)، وأرسل. يعيد الذكاء الاصطناعي قالبًا كاملًا يمكنك لصقه في المحرر وتجميعه.
الصق قالبك الحالي في قسم الملء بدلًا من تركه فارغًا. يستخدمه الذكاء الاصطناعي كنقطة انطلاق، فتنتقل أي تخصيصات أجريتها بالفعل بدلًا من استبدالها بالافتراضي.
الموجه خاص بكل بلوك. لا يظهر زر Copy AI prompt إلا على البلوكات التي تدعم القوالب المخصصة.
القالب الافتراضي الذي تبدأ منه هو نسخة عاملة من ترميز البلوك المدمج، فلديك دائمًا مرجع صحيح قابل للعرض تعدّله بدلًا من صفحة فارغة. الجأ إلى Reset to default كلما أردت استعادة ذلك المرجع.ليس دائمًا تطابقًا حرفيًا. القالب الافتراضي لـ Header يعرض أيضًا logoUrl، الذي لا موضع له في الترميز المدمج، فتفعيل ذلك القالب هو الطريقة التي تظهر بها صورة الترويسة المرفوعة لأول مرة.

​
ما الذي يستبدله قالبك

يستبدل القالب عرض البلوك بالكامل. لا يبقى أي غلاف حول JSX الخاص بك، ولهذا عواقب تستحق المعرفة قبل أن تبدأ في الحذف:
علامة تبويب Design هي ما يفاجئ الناس. أثناء تفعيل قالب مخصص، تُعطَّل حقول علامة تبويب Design وتظهر أيقونة تحذير بجوار عنوان “Design”. مرر فوق الأيقونة لمعرفة السبب. نسّق البلوك من قالبك بدلًا من ذلك، إما مضمّنًا أو بـ CSS الخاص بك. تعود الحقول للعمل فور إيقاف القالب المخصص.
ما تحتفظ به: موضع البلوك في السلة، ومفتاح رؤيته، وإعداداته (التي لا تزال تغذي الخصائص التي تستقبلها)، ولوحة Custom CSS الخاصة بالسلة، وهيكل التحميل المدمج. هذا الأخير يفاجئ الناس. يتحقق البلوك مما إذا كانت السلة لا تزال تُحمَّل قبل الوصول إلى قالبك، لذا يُعرض الهيكل المدمج أثناء التحميل ولا يعمل قالبك إلا بعد جاهزية السلة. لا تحتاج إلى بناء حالة تحميل.

​
ما المتاح داخل القالب

قالبك هو مكوّن دالة واحد. يُجمَّع من TSX، فتُسمح تعليقات الأنواع وتُزال وقت التجميع. لهذا كُتبت القوالب الافتراضية بها:
سطر التوقيع والقوس الختامي مقفلان — لن يسمح لك المحرر بتحرير أي منهما، والتمرير فوقهما يعرض “Locked — this line can’t be edited.” تكتب الجسم بينهما. Reset to default هو الشيء الوحيد الذي يمكنه استبدالهما. ما يهم أيضًا:
  • لديك خمسة خطافات: 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 الخاص بك “لا يعمل” بينما القواعد المدمجة هي الفائزة.
احذف cart-external-* لأنه اسم مشترك، وليس ملكك. تلك الأسماء تعني شيئًا محددًا في الترميز المدمج، وCSS المخصص الخاص بك يُكتب مرة واحدة للسلة بأكملها. إذا أعاد قالب مُعاد الهيكلة استخدامها، فإن أي قاعدة تكتبها تستهدف بنيتك والبنية المدمجة معًا.يسوء ذلك لحظة إيقاف القالب المخصص: يعود البلوك إلى ترميزه المدمج، وCSS الخاص بك لا يزال يشير إليه، فينسّق الآن بنية DOM لم يُكتب لها أبدًا. بادئتك الخاصة تُبقي الاثنين منفصلين بوضوح، فيكون إيقاف القالب عودة نظيفة.
طريقتان لتنسيق ما بنيته:

​
الخيار 1: أسماء أصناف خاصة بك مع Custom CSS

الأفضل لأي شيء ستصونه أو تعيد استخدامه. امنح أصنافك بادئة لن يتصادم بها أحد، عادةً اسم متجرك أو علامتك التجارية:
ثم في محرر السلة، حدد Cart settings في اللوحة اليسرى وافتح علامة تبويب Custom CSS على اليمين:
البادئة أهم مما تبدو. بدونها، صنف مثل .header أو .title معرّض للتصادم مع أصناف السلة نفسها، أو قالب تطبيق آخر، أو بلوك مستقبلي.

​
الخيار 2: الأنماط المضمّنة

بلا ذهاب وإياب مع لوحة CSS، وكل شيء في مكان واحد:
جيد لهيكلة التخطيط والحالات الفردية. حدوده هي المعتادة: لا :hover أو أشباه أصناف أخرى، ولا استعلامات وسائط، ولا إعادة استخدام عبر البلوكات. الجأ إلى الخيار 1 عندما تريد أيًا من ذلك.

​
اختيار المنهج

تُعرض السلة في shadow root، لذا لا يمكن لورقة أنماط قالبك الوصول إلى داخلها. يجب أن تأتي أنماط القالب المخصص من لوحة Custom CSS الخاصة بالسلة أو من أنماط مضمّنة، وليس من قالبك. راجع CSS المخصص.

​
عندما يفشل قالب

القالب المعطوب لا يعطّل السلة أبدًا. يعرض البلوك لا شيء ويستمر كل ما حوله في العمل، وهو أمر آمن لكن يسهل تفويته: العَرَض هو مساحة فارغة حيث ينبغي أن يكون بلوكك. ولأن البلوك يختفي بصمت بدلًا من إظهار خطأ مرئي، افحص القالب دائمًا في المعاينة قبل النشر. إذا اختفى بلوك، فافتح وحدة تحكم المتصفح أولًا. أمران يستحقان الحذر، لأن كليهما يُسقط قالبًا يفترض خلاف ذلك:
  • الخصائص القابلة للقيمة الفارغة. كثير من الخصائص تكون null في الظروف العادية (logoUrl بلا شعار، وimageUrl بلا صورة، وvariantTitle على منتج أحادي النسخة). تحقق قبل استخدامها.
  • المصفوفات التي قد تكون فارغة. discountTags وdiscountCodes تكونان [] في أغلب الأحيان.

​
القيود

  • القوالب المخصصة تجاوزات عرض. لتشغيل منطق على السلة (الاشتراك في الأحداث، إضافة عناصر، التفاعل مع التغييرات)، استخدم السكربتات المخصصة وCart SDK.
  • كل بلوك تقريبًا يدعم قالبًا. الاستثناءات هي بلوك Express payments الذي يستضيف أزرار دفع Shopify نفسها، وحاوية Cart items نفسها، وإن كان صف Product داخلها يدعم قالبًا مخصصًا.
  • لا يمكن للقالب تغيير ما يفعله البلوك جوهريًا. فهو يغيّر طريقة عرض بيانات البلوك، وليس البيانات أو السلوك خلفها.

​
خصائص كل بلوك

يمرر كل بلوك بياناته الخاصة. جدول الخصائص الكامل، مع الأنواع ومثال عملي، موجود في صفحة ذلك البلوك: بلوك Custom code هو الواجهة الوحيدة التي تضيف ترميزًا بدلًا من استبدال عرض بلوك، لذا فإن خصائصه مختلفة: السلة بأكملها، إضافة إلى إجراء إضافة إلى السلة. راجع بلوكات الكود المخصص ← الخصائص.