Agency-ProgressBar: تفاصيل واجهة المستخدم التي ترفع كل سكريبت بهدوء

نص صغير، تأثير كبير

تظهر أشرطة التقدم في كل مكان في FiveM، فتح الأقفال، الإصلاح، غسل الأموال، التعدين، المساعدة الطبية. التنفيذات الافتراضية وظيفية لكنها بسيطة. Agency-ProgressBar هو تصورنا لكيف يجب أن يشعر هذا الأداة عندما يهتم شخص بالتفاصيل.

تشريح شريط التقدم الجيد

شريط تقدم جيد ينقل أربعة أشياء في نفس الوقت: ما الإجراء الذي يحدث، مدى التقدم، كم تبقى من الوقت، وما إذا كان يمكنك الإلغاء. معظم التطبيقات تتعامل فقط مع الأولين. Agency-ProgressBar يعرض الأربعة جميعًا، مع حركات دقيقة تجعل التقدم يبدو سلسًا بدلاً من متقطع.

إلغاء يعمل فعلياً

إلغاء اللاعب يبدأ تحريك تلاشي قصير يعيد شفافية الشريط إلى صفر خلال 300 مللي ثانية. لا اختفاء مفاجئ. يمكن للمطورين تسجيل رد نداء للإلغاء حتى تقوم السكربتات بالتنظيف بشكل صحيح عندما يبتعد اللاعب عن إجراء في منتصف التقدم.

تموضع سياقي

تظهر الشريط بالقرب من العنصر ذي الصلة على الشاشة، فوق رأسك للإجراءات الموجهة لنفسك، وفوق NPC الهدف للإجراءات التفاعلية. لا مزيد من قراءة حالة الإجراء من أسفل الشاشة بينما يحدث شيء في الأعلى. هذا التمركز السياقي هو ترقية UX دقيقة يشعر بها اللاعبون دون أن يتمكنوا من تسميتها.

The Export Pattern

مثل جميع سكربتاتنا المساعدة، تعرض Agency-ProgressBar واجهة برمجة تطبيقات تصدير بسيطة: exports['agency-progressbar']:Play({label, duration, canCancel, onCancel, onDone}). أضفه إلى أي سكريبت خلال دقائق. يتوافق مع Agency-Notify، Agency-Hud، وبقية نظامنا البيئي بدون أي إعداد خاص.

التثبيت & الإعداد

Agency-ProgressBar is a drop-in utility with zero database dependency. Download from Tebex, drop the folder into your resources directory, add ensure agency-progressbar إلى server.cfg. هذا كل شيء. يبدأ المورد بالعمل فورًا ويمكن لأي سكربت استدعاء واجهة برمجة التطبيقات exports عند إعادة التشغيل التالية.

إذا كنت تستبدل شريط تقدم موجود (progressBar من ox_lib، qb-progressbar، إلخ)، فإن البحث والاستبدال في اسم استدعاء التصدير يتعامل مع معظم الترحيلات في دقائق. هيكل المعلمات مقصود أن يكون قريبًا من أنماط المجتمع الشائعة.

خيارات التكوين

مفتوح config.lua لتعديل الإعدادات الافتراضية:

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

توافق الإطار

Agency-ProgressBar is fully standalone with no framework dependencies. It functions identically on QBCore, ESX, and custom server setups. The exports API is the only integration surface, no shared globals, no framework events, no permission checks. Install it and call it from any script regardless of origin.

لماذا هذا مهم للعب التمثيلي

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

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

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

الأسئلة المتكررة

هل يمكنني تشغيل عدة أشرطة تقدم في نفس الوقت؟

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

كيف ألصق شريط تقدم على عنصر أو NPC بدلاً من اللاعب؟

اجتياز target = {type = 'entity', id = entityNetId} الحقل في جدول الخيارات. الشريط يحوم فوق الكيان المحدد بدلاً من اللاعب. استخدم هذا لإجراءات الإصلاح، الإجراءات الطبية على اللاعبين المصابين، أو أي حالة يكون تركيز الإجراء فيها خارجيًا.

هل يمكن إجبار شريط التقدم على عدم الإلغاء من جانب الخادم؟

نعم. اضبط canCancel = false عند استدعاء Play(). مفتاح الإلغاء لا يؤثر ولا يتم تشغيل رسوم إلغاء. هذا مناسب للإجراءات التي يفرضها السيرفر (رسوم اعتقال، مشاهد سينمائية مبرمجة) حيث أن مقاطعة اللاعب ستكسر التدفق.

هل يعمل هذا مع تحريكات ox_lib؟

نعم. Agency-ProgressBar مستقل عن الرسوم المتحركة، أنت تتعامل مع الرسوم المتحركة في سكريبتك الخاص بجانب استدعاء شريط التقدم. الشريط هو عنصر واجهة مستخدم بحت. يمكنك دمجه مع أي مكتبة رسوم متحركة أو استدعاءات رسوم متحركة خام في FiveM بشكل مستقل.

المتطلبات

• خادم FiveM (أي إطار عمل أو مستقل)
• حساب cfx.re مع ترخيص Agency-ProgressBar صالح
• لا اعتماد على قاعدة بيانات
• لا اعتماد على موارد خارجية

أمثلة عملية على التكامل

فيما يلي أنماط شائعة لدمج Agency-ProgressBar مع السكربتات الموجودة:

فتح الأقفال: اتصال Play({label = 'Picking lock...', duration = 8000, canCancel = true, onCancel = cleanupFunction}) في بداية محاولة فتح القفل. اقترن مع لعبة القفل المصغرة التي تعمل بالتوازي. إذا فشلت اللعبة المصغرة، استدعِ Dismiss() مع المعرف المعاد. إذا نجحت، دع الشريط يكتمل بشكل طبيعي.

العلاج الطبي: استخدم target = {type = 'entity', id = patientNetId} لربط الشريط فوق المريض بدلاً من المسعف. يرى اللاعبون الذين يشاهدون المشهد التقدم يحدث عند نقطة العلاج، وليس عائمًا فوق رأس المسعف.

جمع الأدلة: تعيين canCancel = false لجمع الأدلة المبرمجة التي لا يجب مقاطعتها (لمنع اللاعبين من الإلغاء لتجنب ترك بصمات في موقع الحادث). شريط عدم الإلغاء يخبر اللاعب أن هذا الإجراء إلزامي وليس اختياريًا.

الإجراءات على جانب الخادم: شغّل شريط تقدم على العميل أثناء تشغيل إجراء على جانب الخادم بشكل غير متزامن. عندما يعود رد الخادم، إما دع الشريط يكتمل أو ألغِه مبكرًا اعتمادًا على نتيجة جانب الخادم. يجب أن تتطابق المدة البصرية تقريبًا مع الوقت المتوقع لمعالجة الخادم.