مكونات Vue مخصصة في واجهة مولّدة — بأمان مع إعادة التوليد

ما الذي ينكسر حين تعدل واجهة مولدة

الواجهات المولدة مصممة ليجري إعادة بنائها. في منصات مثل AppMaster، يُنتَج كود تطبيقات الويب باستخدام Vue3 من منشئي واجهة مرئية. إعادة التوليد هي الطريقة التي تبقى بها التغييرات متسقة عبر الشاشات والمنطق ونماذج البيانات.

المشكلة بسيطة: إذا عدّلت الملفات المولدة مباشرةً، يمكن لإعادة التوليد التالية أن تمحو تعديلاتك.

لهذا تلجأ الفرق إلى الكود المخصص. قد تغطي العناصر المضمنة الحقول والجداول القياسية، لكن التطبيقات الحقيقية عادةً ما تحتاج بعض العناصر الخاصة: رسوم معقدة، منتقي خرائط، محرّرات نص منسق، لوحات توقيع، أو مخططات سحب وإفلات. هذه أسباب وجيهة لإضافة مكونات Vue مخصصة، بشرط معاملتها كإضافات لا كتعديلات.

عندما يختلط الكود المخصص مع الكود المولَّد، قد تتأخر الأخطاء وتصبح مربكة. قد لا تلاحظها إلا عندما يجبرك تغيير واجهة لاحق على إعادة التوليد، أو عندما يغيّر زميل شاشة في المُنشئ البصري. المشاكل الشائعة تشمل:

• يختفي الوسم المخصص لأن القالب أعيد توليده.
• تنكسر عمليات الاستيراد أو التسجيل لأن أسماء الملفات أو البنية تغيّرت.
• "تصحيح صغير" يتحول إلى تعارض دمج على كل نشر.
• ينحرف المنطق المولَّد والمنطق المخصص، فتبدأ حالات الحافة بالفشل.
• تبدو الترقيات محفوفة بالمخاطر لأنك لا تعرف ما سَيُستبدَل.

الهدف ليس تجنّب التخصيص. بل جعل عمليات إعادة البناء متوقعة. إذا حافظت على حدّ نظيف بين الشاشات المولدة والودجات المخصصة، تبقى إعادة التوليد روتينية بدلًا من أن تكون مرهقة.

قاعدة حدودية تحافظ على سلامة إعادة التوليد

إذا أردت تخصيصًا دون فقدان العمل، اتبع قاعدة واحدة: لا تعدّل الملفات المولَّدة. اعتبرها مُخرَجًا للقراءة فقط، مثل ملف مُجمّع.

فكّر بواجهة المستخدم كمنطقتين:

• المنطقة المولدة: الصفحات، التخطيطات، والشاشات التي ينتجها المولّد.
• المنطقة المخصصة: مكونات Vue التي تكتبها بنفسك في مجلد منفصل.

يجب أن تستهلك الواجهة المولدة مكوناتك المخصصة؛ لا يجب أن تكون المكان الذي تبني فيه هذه المكونات.

لكي ينجح ذلك على المدى الطويل، اجعل "الحد" صغيرًا وواضحًا. يجب أن يتصرف الودجت المخصص كمنتج صغير بعقد:

• الوارد (props): فقط ما يحتاجه للعرض.
• الصادر (events): فقط ما تحتاج الصفحة إلى التفاعل معه.

تجنّب الوصول إلى الحالة العالمية أو استدعاء واجهات برمجة تطبيقات غير ذات صلة من داخل الودجت ما لم يكن ذلك جزءًا صريحًا من العقد.

مع شاشات Vue3 على نمط AppMaster، يعني هذا عادةً أنك تقوم بتوصيل بسيط في الشاشة المولدة لتمرير الخواص ومعالجة الأحداث. قد يتغير هذا التوصيل عبر إعادة التوليد، لكنه يبقى صغيرًا وسهلًا لإعادة تنفيذه. العمل الحقيقي يظل آمنًا في المنطقة المخصصة.

أنماط العزل التي تعمل جيدًا مع Vue3

الهدف واضح: يجب أن تستبدل عمليات إعادة التوليد الملفات المولدة بحرية، بينما يظل كود الودجت الخاص بك دون لمس.

نهج عملي هو إبقاء الودجات المصممة خصيصًا كوحدة داخلية صغيرة: مكونات، أنماط، ومرافق مساعدة في مكان واحد. في تطبيقات Vue3 المولدة، يعني ذلك عادةً أن الكود المخصص يعيش خارج الصفحات المولدة ويُستورد كاعتماد.

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

بعض الأنماط التي تصمد جيدًا:

• عامل الودجت كصندوق أسود: خواص واردة، أحداث صادرة.
• استخدم غلافًا لمطابقة استجابات الـ API والتواريخ والمعرّفات إلى صيغ صديقة للودجت.
• اجعل الأنماط محصورة حتى لا تتجاوز الصفحات المولدة عنصر الودجت بطريق الخطأ.
• لا تعتمد على بنية DOM الأصلية أو أسماء فئات الصفحة الخاصة.

فيما يخص الأنماط، فضّل CSS scoped (أو CSS Modules) وواضع أسماء فئات ذات نطاق (namespace). إذا احتاج الودجت للتوافق مع ثيم التطبيق، مرّر رموز الثيم كخواص (ألوان، تباعد، حجم خط) بدلًا من استيراد أنماط الصفحة.

تُعد الـ slots آمنة عندما تبقى صغيرة وخيارية، مثل رسالة "الحالة الفارغة". إذا بدأت الـ slots بالتحكم في التخطيط أو السلوك الأساسي، فقد أعدت الودجت إلى طبقة المولّد، وهنا تبدأ مشاكل إعادة التوليد.

تصميم عقدة مكوّن مستقرة (الخواص والأحداث)

أكثر الطرق أمانًا للحفاظ على سهولة إعادة التوليد هي معاملة كل ويدجت كواجهة مستقرة. الشاشات المولدة قد تتغير. مكوّنك لا ينبغي أن يتغير.

ابدأ بالمدخلات (props). اجعلها قليلة، متوقعة، وسهلة التحقق. فضّل البدائيات والكائنات البسيطة التي تسيطر عليها. أضف قيمًا افتراضية حتى يتصرف الودجت بشكل جيد حتى لو مرّرت الصفحة لا شيء بعد. إذا كان شيء قد يكون معطوبًا (معرّفات، سلاسل تواريخ، قيم تشبه القوائم)، فعليك التحقق منه والفشل بلطف: عرض حالة فارغة بدلًا من التعطّل.

بالنسبة للمخرجات، قوّم أحداثًا موحّدة بحيث يشعر الودجت بالاتساق مع بقية التطبيق. مجموعة موثوقة قد تكون:

• update:modelValue لدعم v-model
• change للتغييرات المؤكدة من المستخدم (ليس كل ضغطة مفتاح)
• error عندما لا يستطيع المكوّن إتمام مهمته
• ready عندما تنتهي الأعمال غير المتزامنة ويصبح الودجت قابلًا للاستخدام

إذا كان هناك عمل غير متزامن، اجعل ذلك جزءًا من العقد. اكشف عن خواص مثل loading و disabled، وفكّر في errorMessage لأخطاء من الخادم. إذا كان المكوّن يجلب بيانات بنفسه، فصدِر error وready حتى يتفاعل الوالد (إشعار، تسجيل، واجهة بديلة).

توقعات الوصولية

ادمج الوصولية في العقد. اقبل خاصية label (أو ariaLabel)، وثّق سلوك لوحة المفاتيح، واجعل التركيز متوقّعًا بعد الإجراءات.

على سبيل المثال، يجب أن يدعم ويدجت تسلسل زمني على لوحة القيادة مفاتيح الأسهم للتنقل بين العناصر، ومفتاح Enter لفتح التفاصيل، وأن يعيد التركيز إلى التحكم الذي فتح حوارًا عند إغلاقه. هذا يجعل الودجت قابلاً لإعادة الاستخدام عبر شاشات مولدة دون عمل إضافي.

خطوة بخطوة: إضافة ويدجت مخصص دون لمس الملفات المولدة

ابدأ صغيرًا: شاشة واحدة يهتم بها المستخدمون، وودجت واحد يجعلها مميزة. إبقاء التغيير الأولي ضيقًا يجعل من السهل رؤية ما تفعله إعادة التوليد وما لا تفعله.

1. أنشئ المكوّن خارج المنطقة المولدة. ضعه في مجلد تملكه وادخله إلى نظام التحكم بالمصدر (غالبًا مجلد custom أو extensions).

2. اجعل السطح العام صغيرًا. بعض الخواص واردة، وبعض الأحداث صادرة. لا تمرّر حالة الصفحة كاملة.

3. أضف غلافًا رقيقًا تمتلكه أنت أيضًا. مهمته ترجمة "بيانات الصفحة المولدة" إلى عقدة الودجت.

4. ادمجه عبر نقطة امتداد مدعومة. ارجع إلى الغلاف بطريقة لا تتطلب تعديل الملفات المولدة.

5. أعد التوليد وتحقق. يجب أن تبقى مجلداتك المخصصة والغلاف والمكوّن دون تغيير وتستمر عملية التجميع.

احفظ الحدود حادة. يركّز الودجت على العرض والتفاعل. يربط الغلاف البيانات ويحوّل الإجراءات. قواعد العمل تبقى في طبقة منطق التطبيق (الخلفية أو العمليات المشتركة)، وليس مدفونة داخل الودجت.

اختبار صحة سريعة: لو حدثت الآن إعادة توليد، هل يستطيع زميل أن يعيد بناء التطبيق ويحصل على نفس النتيجة دون إعادة إجراء تعديل يدوي؟ إذا كانت الإجابة نعم، فهذا نمط جيد.

أين تضع المنطق حتى تظل الواجهة قابلة للصيانة

يجب أن يهتم الودجت المخصص في الغالب بكيفية المظهر وكيفية استجابة عناصره لإدخال المستخدم. كلما ضمّنت قواعد عمل داخل الودجت، صار من الصعب إعادة استخدامه واختباره وتغييره.

الافتراض الجيد: احتفظ بمنطق العمل في مستوى الصفحة أو الميزة، وخذ الودجت "غبيًا". تقرر الصفحة أي بيانات يحصل عليها الودجت وماذا يحدث عند صدور حدث منه. يعرض الودجت ويبلغ عن نية المستخدم.

عندما تحتاج منطقًا قريبًا من الودجت (تنسيق، حالة صغيرة، تحقق على العميل)، اخفِه وراء طبقة خدمة صغيرة. في Vue3 قد تكون وحدة، composable، أو متجرًا بواجهة واضحة. يستورد الودجت تلك الواجهة، لا يستورد تفاصيل التطبيق العشوائية.

تقسيم عملي:

• الودجت (component): حالة العرض، معالجة الإدخال، المظهر، يصدر أحداثًا كـ select, change, retry.
• الخدمة/composable: تشكيل البيانات، التخزين المؤقت، تحويل أخطاء API إلى رسائل للمستخدم.
• الصف/الحاوية: قواعد العمل، الأذونات، أي بيانات تُحمّل ومتى تُحفَظ.
• أجزاء التطبيق المولدة: اتركها دون لمس؛ مرّر البيانات واستمع للأحداث.

تجنّب الاستدعاءات API المباشرة داخل الودجت ما لم يكن ذلك جزءًا من عقده. إذا امتلك جلب البيانات، اجعل ذلك واضحًا في الاسم (مثل CustomerSearchWidget) وضع كود الاستدعاء في خدمة واحدة. وإلا، مرّر items, loading, و error كخواص.

يجب أن تكون رسائل الخطأ موجهة للمستخدم ومتسقة. بدلًا من عرض نص الخادم الخام، حوّل الأخطاء إلى مجموعة صغيرة من الرسائل المتعارف عليها في التطبيق، مثل "تعذر تحميل البيانات. حاول مرة أخرى." أضف إجراء إعادة المحاولة عندما يكون ممكنًا، وسجّل الأخطاء التفصيلية خارج الودجت.

مثال: لا يجب أن يقرّر ويدجت ApprovalBadge ما إذا كانت الفاتورة قابلة للموافقة. دَع الصفحة تحسب status وcanApprove. يبادر الشارة بحدث approve، وتنفيذ القاعدة الحقيقية يتم في الصفحة التي تستدعي الخلفية، ثم تعيد الحالة النظيفة إلى الواجهة.

أخطاء شائعة تسبب ألمًا بعد إعادة التوليد التالية

معظم المشكلات ليست متعلقة بـ Vue نفسها. بل تنشأ من دمج العمل المخصص في أماكن يملكها المولّد، أو الاعتماد على تفاصيل من المرجح أن تتغير.

الأخطاء التي تحوّل ويدجت صغير إلى تنظيف متكرر:

• تحرير ملفات Vue المولدة مباشرة ونسيان ما تغيّر.
• استخدام CSS عام أو محددات واسعة تؤثر بصمت على شاشات أخرى عندما يتغيّر الوسم.
• قراءة أو تعديل أشكال الحالة المولدة مباشرة، بحيث يكسر تغيير اسم بسيط الودجت.
• حشر افتراضات صفحة محددة في مكوّن واحد.
• تغيير واجهة المكوّن (الخواص/الأحداث) بدون خطة ترحيل.

سيناريو شائع: تضيف ويدجت جدول مخصص ويعمل. بعد شهر، تغير في التخطيط المولّد يجعل قاعدة .btn العامة تؤثر على صفحات تسجيل الدخول والإدارة. أو تغيّر كائن البيانات من user.name إلى user.profile.name وتفشل المكون بصمت. المشكلة ليست في المكوّن بالضرورة، بل في الاعتماد على تفاصيل غير مستقرة.

عادتان تمنعان معظم هذا:

أولًا، اعتبر الكود المولَّد للقراءة فقط واحتفظ بالملفات المخصصة منفصلة مع حد استيراد واضح.

ثانيًا، اجعل عقد المكوّن صغيرًا وصريحًا. إذا احتجت لتطوّره، أضف خاصية إصدار بسيطة (مثلاً apiVersion) أو دعم أشكال خواص قديمة وجديدة خلال إصدار واحد.

قائمة فحص سريعة قبل شحن مكوّن مخصص

قبل دمج ويدجت مخصص في تطبيق Vue3 مولّد، قم بفحص سريع للواقع. يجب أن ينجو من إعادة التوليد التالية دون بطولات، ويجب أن يتمكن شخص آخر من إعادة استخدامه.

• اختبار إعادة التوليد: نفّذ إعادة توليد كاملة وأعد البناء. إذا اضطررت لإعادة تحرير ملف مولّد، فالحدّ خاطئ.
• مدخلات ومخرجات واضحة: خواص واردة، أحداث صادرة. تجنّب الاعتماد السحري على DOM خارجي أو مخزن صفحة محدد.
• احتواء الأنماط: اجعل الأنماط محدودة واستخدم بادئة فئة واضحة (مثلاً timeline-).
• جميع الحالات مرئية: حالات التحميل، الخطأ، والفراغ يجب أن تكون موجودة ومعقولة.
• إعادة الاستخدام بدون استنساخ: تأكد أنه يمكنك إسقاطه في صفحة ثانية بتغيير الخواص ومعالجات الأحداث، لا بنسخ البُنى الداخلية.

طريقة سريعة للتحقق: تخيل إضافة الودجت إلى شاشة إدارة ثم إلى بوابة العملاء. إذا نجح كلاهما بتغييرات خواص ومعالجات أحداث فقط، فأنت في منطقة آمنة.

مثال واقعي: إضافة ويدجت تسلسلي إلى لوحة قيادة

غالبًا ما يريد فريق الدعم شاشة تروي قصة التذكرة: تغييرات الحالة، ملاحظات داخلية، ردود العملاء، وأحداث الدفع أو التسليم. يتناسب ويدجت تسلسلي هنا، لكن لا تريد تعديل الملفات المولدة وفقدان العمل بعد إعادة التوليد التالية.

النهج الآمن هو إبقاء الودجت معزولًا خارج الواجهة المولدة وإدخاله في الصفحة عبر غلاف رقيق.

عقد الودجت

اجعله بسيطًا ومتوقعًا. على سبيل المثال، يمرّر الغلاف:

• ticketId (سلسلة)
• range (آخر 7 أيام، آخر 30 يومًا، مخصص)
• mode (مضغوط مقابل تفصيلي)

يصدر الودجت:

• select عندما ينقر المستخدم حدثًا
• changeFilters عندما يغيّر المستخدم النطاق أو الوضع

الآن لا يعرف الودجت شيئًا عن صفحة اللوحة أو نماذج البيانات أو كيفية إجراء الطلبات. يعرض تسلسلاً زمنيًا ويبلغ عن إجراءات المستخدم.

كيف يربطه الغلاف بالصفحة

يقع الغلاف بجوار اللوحة ويحوّل بيانات الصفحة إلى العقدة. يقرأ رقم التذكرة الحالي من حالة الصفحة، يحوّل مرشحات الواجهة إلى range، ويحوّل سجلات الخلفية إلى صيغ الأحداث التي يتوقعها الودجت.

عندما يصدر الودجت select، يمكن للغلاف فتح لوحة تفاصيل أو تفعيل إجراء صفحة. عند changeFilters، يحدث الغلاف مرشحات الصفحة ويعيد تحميل البيانات.

عند إعادة توليد واجهة اللوحة، يبقى الودجت لم يمس لأنّه يعيش خارج الملفات المولدة. عادةً ما تزور الغلاف فقط إذا أعادت الصفحة تسمية حقل أو غيّرت طريقة تخزين المرشحات.

عادات الاختبار والإصدار التي تمنع المفاجآت

تفشل المكونات المخصصة عادةً بأشكال مملة: يتغير شكل خواص، يتوقف حدث عن الإطلاق، أو تعيد الصفحة المولدة العرض أكثر مما توقعه الودجت. بعض العادات تلتقط هذه المشاكل مبكرًا.

اختبار محلي: اكتشف كسور الحدود مبكرًا

عامل الحد بين الواجهة المولدة وودجتك مثل واجهة برمجة تطبيقات. اختبر الودجت بدون التطبيق الكامل أولًا، مستخدمًا خواص ثابتة تطابق العقدة.

عرّضه بمُدخلات "المسار السعيد" وبقيم مفقودة. قم بمحاكاة الأحداث الرئيسية (حفظ، إلغاء، اختيار) وتأكد أن الوالد يتعامل معها. اختبر بيانات بطيئة وشاشات صغيرة. تحقق ألا يكتب في الحالة العالمية ما لم يكن ذلك جزءًا من العقد.

إذا كنت تبني على تطبيق AppMaster Vue3، قم بهذه الفحوص قبل أن تعيد التوليد. من الأسهل تشخيص كسر حدود عندما لم تغيّر شيئين في آن واحد.

تراجع بعد إعادة التوليد: ما الذي تعيده للاختبار أولًا

بعد كل إعادة توليد، أعد اختبار نقاط التلامس: هل تُمرَّر نفس الخواص، وهل تُعالَج نفس الأحداث؟ هنا يظهر العطل عادة أولًا.

اجعل الإدراج متوقعًا. تجنّب الاستيرادات الهشة التي تعتمد على مسارات ملفات قد تتحرك. استخدم نقطة دخول مستقرة واحدة لمكوناتك المخصصة.

للإنتاج، أضف تسجيلًا خفيفًا والتقاط أخطاء داخل الودجت:

• عند التركيب مع الخواص الأساسية (مُنقحة)
• انتهاكات العقد (خاصية مطلوبة مفقودة أو نوع خاطئ)
• فشل استدعاءات API مع رمز خطأ قصير
• حالات فارغة غير متوقعة

عندما يكسر شيء، تريد سريعًا أن تعرف: هل غيرت إعادة التوليد المدخلات، أم تغيّر الودجت؟

الخطوات التالية: اجعل النمط قابلاً للتكرار عبر تطبيقك

بمجرد أن يعمل الودجت الأول، الربح الحقيقي هو جعله متكررًا حتى لا يكون التالي حلاقة عشوائية.

أنشئ معيارًا داخليًا صغيرًا لعقود الودجات ودوّنه حيث يحتفظ الفريق بملاحظات التطبيق. اجعله بسيطًا: التسمية، الخواص المطلوبة مقابل الاختيارية، مجموعة أحداث صغيرة، سلوك الأخطاء، وملكية واضحة (ما يعيش في الواجهة المولدة مقابل مجلدك المخصص).

اكتب أيضًا قواعد الحدود بلغة بسيطة: لا تعدّل الملفات المولدة، احتفظ بالكود المخصص معزولًا، ومرّر البيانات فقط عبر الخواص والأحداث. هذا يمنع "التصحيح السريع" الذي يتحول إلى ضريبة صيانة دائمة.

قبل بناء ويدجت ثانٍ، قم بتجربة إعادة توليد صغيرة. سلِّم الودجت الأول، ثم أعد التوليد مرتين على الأقل أثناء تغييرات عادية (تغيير تسمية، تغيير تخطيط، حقل جديد) وتأكد من أن لا شيء يكسر.

إذا كنت تستخدم AppMaster، غالبًا ما يكون الأفضل الاحتفاظ بمعظم الواجهة والمنطق في المحرّرات البصرية (منشئ الواجهة، محرر عمليات الأعمال، ومصمم البيانات). احفظ المكونات المخصصة للودجات الحقيقية التي لا يمكن للمحرّرات التعبير عنها، مثل التسلسلات الزمنية المتخصصة أو تفاعلات الرسوم. إذا أردت نقطة بداية نظيفة لهذا الأسلوب، فـ AppMaster على appmaster.io مصمَّم حول إعادة التوليد، لذا يصبح عزل الودجات المخصصة جزءًا طبيعيًا من سير العمل.