spaghettify
1.0.0
يقوم Spaghettify بتحويل أي موقع HTML ثابت إلى تطبيق صفحة واحدة مع التنقل المعتمد على AJAX وعناصر DOM التي تشبع ميزات الثبات. للقيام بذلك، يقوم بتطبيق اعتراض DOM ومعالج تحويل البرامج الوسيطة الذي يلتقط أحداث النقر على الرابط، ويجلب كل مستند مطلوب عبر XHR ويستوعب الاستجابة عن طريق دفقها عبر سلسلة من وظائف البرامج الوسيطة قبل تحديث مستند المتصفح.
وظائف البرامج الوسيطة هذه عبارة عن معالجات إدخال/إخراج قابلة للتوصيل والتي تراعي مبدأ المسؤولية الفردية وتوافق سلسلة كاملة من الخطوات، والتي يمكن تصنيفها إلى خطافات برمجية وسيطة onBeforeComplete ، والتي لا تغير صفحة DOM الحالية، وخطافات برمجية وسيطة onAfterComplete التي تطبق تغييراتها (وبالتالي التحور) مباشرة على صفحة DOM الحالية بعد أن يتم حقنها.
تم بناء المشروع بأكمله على TypeScript وينفذ العديد من استراتيجيات التعبئة المتعددة والتشفير لتوسيع الدعم للمتصفحات القديمة، مثل MSIE11.
الحد الأدنى من المتطلبات لتشغيل هذا المشروع، سواء في وضع التطوير أو الإنتاج، ونصوص التطوير الخاصة به هي node v12.16.0 و npm v.6.14.15 ، أو الإصدارات الأحدث. من المحتمل أن يعمل هذا المشروع بسلاسة على الإصدارات الأقدم من node و npm ولكننا نوصي باستخدام أحدث إصدارات LTS.
يعتمد هذا المشروع على BabelJS وWebpack لتجميع التعليمات البرمجية في وضع التطوير، وتشغيل الإصدارات لخدمة ملفات الموقع التجريبي ومعالجة تحسينات التعليمات البرمجية.
تم تلخيص كل التفاعلات مع BabelJS و Webpack في نصوص npm مخصصة لراحتك.
كخطوة أولى لإنشاء بيئة تطوير أو بناء إنتاج، يرجى تشغيل تثبيت yarn أو npm install لسحب جميع التبعيات المطلوبة لهذا المشروع.
يرجى تنفيذ yarn build أو npm run build من نافذتك الطرفية.
سوف يتنقل مجمّع المشروع عبر شجرة التطبيق بأكملها وسينشئ عناصر JavaScript في المجلد /dist ، المجمّع كـ spaghettify.js . سيتم حفظ الحزم المفيدة الأخرى هناك أيضًا من أجل راحتك.
هل يمكنني جلب Spaghettify من سجل npm؟ في وقت كتابة هذه السطور، تتمثل أولويات المشروع في زيادة تغطية الاختبار بشكل أكبر قليلاً وتوسيع إمكانيات واجهة برمجة التطبيقات (API) مع دعم موسع لخطافات البرامج الوسيطة التي يوفرها المستخدم. في الوقت الحالي، من المفترض أن يتم استخدام Spaghettify كأحد تبعيات المتصفح، ولكن توزيعها كحزمة NPM موجود في خريطة الطريق. يرجى التحقق مرة أخرى قريبا للحصول على التحديثات.
يمكنك إنشاء مثيل لـ Spaghettify والتفاعل معه من خلال واجهة برمجة التطبيقات (API) الملائمة التي تلبي أدوات التبديل العالمية، واعتراضات المسار، والاستثناءات، وعلامات سمات استمرار الحالة، وأخيرًا وليس آخرًا، تحميل مؤشرات التقدم والمعالجات.
بمجرد الانتهاء من ترجمة Spaghettify بنجاح، يمكنك استيرادها وإنشاء مثيل لها في التطبيق الخاص بك على النحو التالي:
< script type =" text/javascript " src =" /dist/spaghettify.js " > </ script >
< script type =" text/javascript " >
new Spaghettify ( {
enabled : true ,
routes : [ '*.html' , 'content/*' ] ,
excludeByAttr : 'no-spa' ,
loadProgress : true ,
persistAttr : 'data-persist' ,
} ) ;
</ script >كما ترون، يمكن لـ Spaghettify أخذ كائن التكوين عند إنشاء مثيل له. يرجى ملاحظة أن جميع الحقول اختيارية وحتى كائن التكوين بأكمله اختياري أيضًا. إذا لم يتم توفيره، فسيتم إنشاء مثيل لـ Spaghettify بالخيارات الافتراضية كما هو موضح في الجدول أدناه.
يمكن تلخيص كائن إعدادات التكوين Spaghettify على النحو التالي:
| مجال | يكتب | تقصير | وصف |
|---|---|---|---|
enabled | Boolean | true | تمكين أو تعطيل Spaghettify عند إنشاء مثيل |
routes | String[] | ['*'] | يحدد أنماط الطرق التي سيتم اعتراضها وتقديمها من خلال Spaghettify. يدعم الرموز العالمية. |
excludeByAttr | String | undefined | يحدد رمزًا مميزًا لسمة بيانات الاستبعاد (مع أو بدون بادئة data- ). سيتم تجاوز الروابط المزينة بهذه السمة بواسطة Spaghettify |
loadProgress | Function Boolean | false | تمكين شريط التقدم المدمج أم لا. يمكن أن يستغرق أيضًا معالج دالة سيتلقى عددًا صحيحًا لنسبة التقدم عند التحميل. |
persistAttr | String | undefined | يحدد سمة بيانات علامة ثبات حالة واجهة المستخدم (مع أو بدون بادئة data- ). ستظل العناصر المزينة بهذه السمة في حالتها عبر التنقل في الصفحة. |
يرجى ملاحظة أن جميع خيارات التكوين (وحمولة الخيارات نفسها) اختيارية وستأخذ القيمة الافتراضية إذا لم يتم الإعلان عنها صراحة.
يتفاعل Spaghettify مع مستندك الحالي عن طريق ربط معالجات الأحداث داخليًا بالارتباطات المؤهلة. من أجل منع تسرب الذاكرة أو إذا كنت تريد إيقاف Spaghettify حتى يتم إعادته مرة أخرى، فسوف تحتاج إلى تدميره على النحو التالي:
< script type =" text/javascript " >
// First, we instantiate Spaghettify
const spa = new Spaghettify ( ) ;
// Then we dispose it after use
spa . destroy ( ) ;
</ script > يتم تكوين جميع الروابط بواسطة Spaghettify كموضوع ليتم اعتراضه. ستقوم آلية إدارة الأحداث الداخلية بتقييم ما إذا كان الرابط مؤهلاً ليتم التعامل معه على أنه طلب AJAX أم لا عن طريق اختبار قيمة href للرابط مقابل الرموز المميزة routes .
ومع ذلك، يمكننا تجاوز هذه الخطوة مقدمًا عن طريق تكوين خيار excludeByAttr بقيمة سمة، إما باستخدام البادئة data- أو لا.
ومع ذلك، ومن أجل دلالات الألفاظ، فإن Spaghettify لن يأخذ في الاعتبار سوى عناصر الارتباط التي تم تكوينها باستخدام السمة الكاملة.
< script type =" text/javascript " >
new Spaghettify ( {
excludeByAttr : 'skip-me' ,
} ) ;
</ script >
<!-- Spaghettify will disregard the following link -->
< a href =" foo.html " data-skip-me > Skip this link </ a >يمكن ملء السمة المكونة بأي قيمة أو لا شيء على الإطلاق. سوف يتجاهل Spaghettify هذه القيمة على أي حال.
كما رأينا سابقًا، يمكن أن يأخذ خيار التكوين loadProgress قيمة منطقية Boolean أو معالج دالة .
< script type =" text/javascript " >
new Spaghettify ( {
loadProgress : true ,
} ) ;
</ script > إذا لم يتم تكوينه بشكل صريح، أو تم تعيينه على false ، فلن يتم عرض أي مؤشر لشريط التقدم. إذا تم توفيره على أنه true ، فسوف يعرض Spaghettify مؤشر شريط تقدم أحمر متحرك أعلى إطار العرض. يعرض شريط التقدم تقدم التنزيل الفعلي.
ومع ذلك، قد يرغب المستهلكون في تنفيذ الحلول المرئية الخاصة بهم لعرض معلومات تقدم التنزيل. يقوم Spaghettify بتغطيتها من خلال توفير معالج تقدم التحميل الذي يتوقع معلمة قيمة عددية في توقيعه، والتي ستأخذ القيم من 0 إلى 100 عند طلب الصفحات وتنزيلها عبر HXR.
< script type =" text/javascript " >
new Spaghettify ( {
loadProgress : function onLoad ( progress ) {
console . log ( progress ) ; // Will log values from 0 to 100
} ,
} ) ;
</ script > تطبق Spaghettify واجهة برمجة تطبيقات تجريبية لاستمرار الحالة في عقد DOM المحددة والموضحة عبر التنقل في الصفحة. وللقيام بذلك، تحتاج فقط إلى تكوين رمز مميز للقيمة في خيار persistAttr ثم إضافة تعليق توضيحي لعناصر DOM التي تريد أن تستمر حالتها باستخدام سمة data- المكافئة بقيمة فريدة لكل منها:
< script type =" text/javascript " >
new Spaghettify ( {
persistAttr : 'persist-id' ,
} ) ;
</ script >
< input type =" text " data-persist-id =" my-input " /> يمكنك بادئة القيمة بشكل صريح بـ data- أو لا، لكن Spaghettify سيطلب منك إضافة تعليق توضيحي إلى عناصر DOM لتستمر مع بناء جملة سمة البيانات الكاملة.
يرجى ملاحظة : يجب أن تكون قيم السمات فريدة. سوف يقوم Spaghettify بطرح استثناء إذا تم تكوين أكثر من عنصر واحد من نوع مختلف بنفس قيمة السمة.
تجدر الإشارة إلى أنه سيتم تطبيق الثبات على أساس DOM Node الكامل، لذلك لن يشمل HTML الداخلي للعنصر فحسب، بل سيشمل أيضًا حالة اللمس الأصلية لعناصر التحكم في الإدخال. وكل هذا بغض النظر عن التغييرات في HTML الخارجي.
يمكنك إنشاء بيئة تطوير عن طريق تشغيل yarn dev أو npm run dev في وحدة التحكم.
سيقوم النظام بإنشاء كافة العناصر وخدمة موقع الحماية (مزيد من التفاصيل أدناه) من http://localhost:3000 (أو أي منفذ آخر من اختيارك إذا قمت بإلحاق --port=PORT المعلمة إلى أمر dev ، حيث PORT هو المنفذ المطلوب) في وضع المراقبة ، لذلك سيتم إعادة ترجمة التطبيق عند حدوث تغييرات في كود المصدر.
موقع Sandbox هو تطبيق ويب صغير ومبسط للغاية يعمل كملعب وساحة اختبار لتصحيح أخطاء Spaghettify في بيئة حية. ويتميز بتصميم مبسط للغاية، من خلال مجموعة من الصفحات الهرمية المختلفة التي تصور الميزات الرئيسية التالية:
index.html الرئيسي على نسخة من Spaghettify المضمّنة لأغراض العرض التوضيحي. تقوم جميع المستندات الأخرى بتنفيذ مثل هذا المثيل مثل البرنامج النصي المستورد. لا تحتاج إلى استيراد Spaghettify في كل مستند، فقط الإدخال واحد. ومع ذلك، يسمح هذا بتشغيل Spaghettify من أي مستند بعد إعادة تحميل نافذة المتصفح لأغراض العرض التوضيحي. في سيناريو الإنتاج الحقيقي، يمكن (ويجب) استيراد Spaghettify وإنشاء مثيل له مرة واحدة فقط في موقع الإدخال./sandbox والمجلد الفرعي /sandbox/content حتى يتمكن المساهمون من اللعب باستخدام محددات الارتباط التي تشير إلى المجلدات الفرعية، إذا لزم الأمر./sandbox/content إما بجافا سكريبت مخصص مضمن أو مستورد والذي سوف يقوم Spaghettify بهضمه وإعادة إدخاله وتنفيذه عند الحاجة. تم تمكين ESLint حاليًا في قاعدة بيانات Spaghettify وسيتم تشغيل عملية تدقيق الفحص عند إنشاء المشروع. يمكنك تكوين IDE الخاص بك لتوفير تقييم الفحص تلقائيًا أثناء إدخال التغييرات. علاوة على ذلك، يمكنك تشغيل عملية فحص التعليمات البرمجية في أي وقت عن طريق تشغيل npm run lint أو yarn lint في وحدة التحكم الطرفية الخاصة بك.
يمكنك إدخال الاختبارات في قاعدة التعليمات البرمجية أو تنفيذ الاختبارات الموجودة عن طريق تشغيل npm test أو yarn test في وحدة التحكم الطرفية الخاصة بك. يتم جمع بيانات تغطية الكود وتخزينها في مستند منسق بشكل ملائم على /coverage/lcov-report . لإعداد تقارير التغطية على الشاشة، يرجى إلحاق معلمة --coverage بأمر test .
يمكنك أيضًا التحقق عبر الإنترنت من تقرير تغطية الاختبار الشامل على Coveralls.
حقوق الطبع والنشر 2021 بابلو ديليمان
يُمنح الإذن مجانًا لأي شخص يحصل على نسخة من هذا البرنامج وملفات الوثائق المرتبطة به ("البرنامج")، للتعامل في البرنامج دون قيود، بما في ذلك، على سبيل المثال لا الحصر، حقوق الاستخدام والنسخ والتعديل والدمج. ونشر و/أو توزيع وترخيص من الباطن و/أو بيع نسخ من البرنامج، والسماح للأشخاص الذين تم توفير البرنامج لهم بالقيام بذلك، وفقًا للشروط التالية:
يجب تضمين إشعار حقوق الطبع والنشر أعلاه وإشعار الإذن هذا في جميع النسخ أو الأجزاء الكبيرة من البرنامج.
يتم توفير البرنامج "كما هو"، دون أي ضمان من أي نوع، صريحًا أو ضمنيًا، بما في ذلك، على سبيل المثال لا الحصر، ضمانات القابلية للتسويق والملاءمة لغرض معين وعدم الانتهاك. لا يتحمل المؤلفون أو أصحاب حقوق الطبع والنشر بأي حال من الأحوال المسؤولية عن أي مطالبة أو أضرار أو مسؤولية أخرى، سواء في إجراء العقد أو الضرر أو غير ذلك، الناشئة عن أو خارج أو فيما يتعلق بالبرنامج أو الاستخدام أو المعاملات الأخرى في برمجة.
