الفرق بين المراجعتين ل"Bootstrap/javascript"
(إنشاء صفحة JavaScript ضمن توثيق Bootstrap) |
(تصويبات متفرقة) |
||
| سطر 1: | سطر 1: | ||
| − | أنعش Bootstrap بملحقات [[JavaScript]] الاختيارية المبنية على [[jQuery]]. | + | أنعش Bootstrap بملحقات [[JavaScript]] الاختيارية المبنية على [[jQuery]]. احصل على معلومات عن كل ملحق، وخيارات البيانات وواجهة التطبيقات البرمجية API وأمور أخرى. |
== فردية أو مجمَّعة == | == فردية أو مجمَّعة == | ||
| − | يمكن تضمين ملحقات فرديَّا (باستخدام ملفات <code>*.js</code> مُفرَدة من مجلّد Bootstrap) أو تضمين جميع الملحقات دفعة واحدة بالملف <code>bootstrap.js</code> أو نسخته المصغَّرة <code>bootstrap.min.js</code> (لا تضمّن الاثنين | + | يمكن تضمين ملحقات فرديَّا (باستخدام ملفات <code>*.js</code> مُفرَدة من مجلّد <code>Bootstrap</code>) أو تضمين جميع الملحقات دفعة واحدة بالملف <code>bootstrap.js</code> أو نسخته المصغَّرة <code>bootstrap.min.js</code> (لا تضمّن الاثنين معًا). |
== الاعتماديّات == | == الاعتماديّات == | ||
| − | تعتمد بعض المحلقات وعناصر [[CSS]] على ملحقات أخرى. تأكّد عند تضمين الملحقات فرديًّا من التحقّق من الاعتماديّات في التوثيقات. انتبه كذلك إلى | + | تعتمد بعض المحلقات وعناصر [[CSS]] على ملحقات أخرى. تأكّد عند تضمين الملحقات فرديًّا من التحقّق من الاعتماديّات في التوثيقات. انتبه كذلك إلى أنَّ '''الملحقات جميعها تعتمد على [[jQuery]]''' (يعني هذا أنه يجب تضمين [[jQuery]] قبل ملفات الملحقات). راجع الملف <code>package.json</code> لرؤية إصدارات [[jQuery]] المدعومة. |
| − | تعتمد القوائم المنسدلة | + | تعتمد [[Bootstrap/dropdowns|القوائم المنسدلة (Dropdowns)]]، [[Bootstrap/popovers|والعناصر المنبثقة (Popovers)]]، [[Bootstrap/tooltips|والتلميحات (Tooltips)]] جميعها على [https://popper.js.org/ Popper.js]. |
== خاصيّات البيانات == | == خاصيّات البيانات == | ||
| − | يمكن تفعيل ملحقات Bootstrap كلّها تقريبا | + | يمكن تفعيل ملحقات Bootstrap كلّها تقريبا وإعدادهًا بواسطة [[HTML]] وحده عن طريق خاصيّات البيانات (data attributes، وهي طريقة مطوّري Bootstrap التي يفضّلونها على استخدام [[JavaScript]]). تأكّد من '''استخدام مجموعة واحدة فقط من خاصيّات البيانات على عنصُر معيَّن''' (مثلاً؛ لا يمكن إظهار [[Bootstrap/tooltips|تلميح]] وفتح [[Bootstrap/modal|مربعات الحوار [Modal]]] بنفس الزّر). |
| − | يُرغَب | + | يُرغَب أحيانًا في تعطيل الوظيفة المذكورة أعلاه. إن كنت ترغب في تعطيل واجهة التطبيقات البرمجية الخاصّة بخاصيّات البيانات فيمكنك ذلك بفصل جميع الأحداث في مجال الأسماء <code>data-api</code> من المستند؛ على النحو التالي:<syntaxhighlight lang="javascript"> |
$(document).off('.data-api') | $(document).off('.data-api') | ||
| − | </syntaxhighlight>كما يمكنك | + | </syntaxhighlight>كما يمكنك بدلًا من ذلك استهداف ملحق محدَّد بذكر اسمه ضمن فضاء الأسماء <code>data-api</code> على النحو التالي:<syntaxhighlight lang="javascript"> |
$(document).off('.alert.data-api') | $(document).off('.alert.data-api') | ||
</syntaxhighlight>'''تنبيه:''' تأكّد من تخليص المحدّدات المخصَّصة مثل <code>collapse:Example</code> إن كنت تستخدمها، إذ أنها ستمرّ عبر jQuery. | </syntaxhighlight>'''تنبيه:''' تأكّد من تخليص المحدّدات المخصَّصة مثل <code>collapse:Example</code> إن كنت تستخدمها، إذ أنها ستمرّ عبر jQuery. | ||
== الأحداث == | == الأحداث == | ||
| − | يوفّر Bootstrap أحداثًا مخصَّصة لأغلب الإجراءات الفريدة للملحقات. تأتي هذه الأحداث | + | يوفّر Bootstrap أحداثًا مخصَّصة لأغلب الإجراءات الفريدة للملحقات. تأتي هذه الأحداث عمومًا بصيغتيْن تُسمَّى الأولى بأفعال إنكليزية مصدرية (<code>show</code>) والثانية بأسماء مفعولة (<code>shown</code>). تُطلَق الصيغة الأولى عند بداية الحدث فيما تُطلَق الثانية بعد اكتمال الحدث. |
| − | توفّر جميع الأحداث التي تحمل أسماء بأفعال مصدرية التابع <code>[ | + | توفّر جميع الأحداث التي تحمل أسماء بأفعال مصدرية قدرةً على استعمال التابع <code>[[JavaScript/Event/preventDefault|preventDefault()]]</code> الذي يمنح إمكانية إيقاف الحدث قبل أن يبدأ. يؤدّي إرجاع القيمة <code>false</code> من مُعالج الأحداث (Event handler) إلى استدعاء التابع <code>preventDefault()</code> تلقائيًا.<syntaxhighlight lang="javascript"> |
$('#myModal').on('show.bs.modal', function (e) { | $('#myModal').on('show.bs.modal', function (e) { | ||
if (!data) return e.preventDefault() // يوقف إظهار نافذة شرطية | if (!data) return e.preventDefault() // يوقف إظهار نافذة شرطية | ||
| سطر 28: | سطر 28: | ||
== واجهة تطبيقات برمجية == | == واجهة تطبيقات برمجية == | ||
| − | يرى فريق Bootstrap أنه يجب أن يكون المبرمج | + | يرى فريق Bootstrap أنه يجب أن يكون المبرمج قادرًا على استخدام جميع ملحقات Bootstrap ببساطة عن طريق واجهة برمجية API باستخدام [[JavaScript]]. جميع الواجهات البرمجية في Bootstrap هي توابع منفردة يمكن استدعاؤها بالتتالي وتُرجِع المجموعة التي نُفِّذت عليها الإجراءات:<syntaxhighlight lang="javascript"> |
$('.btn.danger').button('toggle').addClass('fat') | $('.btn.danger').button('toggle').addClass('fat') | ||
| − | </syntaxhighlight>يجب أن تتلقّى جميع التوابع إما كائنَ خيارات اختياري، سلسلة محارف تستهدف | + | </syntaxhighlight>يجب أن تتلقّى جميع التوابع إما كائنَ خيارات اختياري، أو سلسلة محارف تستهدف تابعًا مخصوصًا، أو لا شيء (وفي هذه الحالة يُلجَأ للسلوك المبدئي للملحَق):<syntaxhighlight lang="javascript"> |
$('#myModal').modal() // تُستهَل نافذة شرطية بالخيارات المبدئية | $('#myModal').modal() // تُستهَل نافذة شرطية بالخيارات المبدئية | ||
$('#myModal').modal({ keyboard: false }) // تُستهَل نافذة شرطية بدون لوحة مفاتيح | $('#myModal').modal({ keyboard: false }) // تُستهَل نافذة شرطية بدون لوحة مفاتيح | ||
$('#myModal').modal('show') // تُستهَل نافذة شرطية بالتابع show وتُعرض مباشرة | $('#myModal').modal('show') // تُستهَل نافذة شرطية بالتابع show وتُعرض مباشرة | ||
| − | </syntaxhighlight>يقدّم كلّ مُلحَق | + | </syntaxhighlight>يقدّم كلّ مُلحَق دالةً بانيةً (Constructor) في الخاصيّة <code>Constructor</code>، مثلا <code>$.fn.popover.Constructor</code>. يمكنك الحصول على نسخة (Instance) مُلحَق مخصوصة من العنصُر مباشرة <code>$('[rel="popover"]').data('popover')</code>. |
=== الدوال غير المتزامنة والانتقالات === | === الدوال غير المتزامنة والانتقالات === | ||
| − | جميع توابع واجهة التطبيقات البرمجية '''غير متزامنة''' Asynchronous وتعود إلى المُستدعي مباشرة بعد بدء الانتقال ولكن '''قبل أن يكتمل'''. | + | جميع توابع واجهة التطبيقات البرمجية '''غير متزامنة''' (Asynchronous) وتعود إلى المُستدعي مباشرة بعد بدء الانتقال ولكن '''قبل أن يكتمل'''. |
يجب الإنصات إلى الحدث المُصاحب لاكتمال الانتقال إن كنت تريد تنفيذ إجراء بعد اكتمال الحدث.<syntaxhighlight lang="javascript"> | يجب الإنصات إلى الحدث المُصاحب لاكتمال الانتقال إن كنت تريد تنفيذ إجراء بعد اكتمال الحدث.<syntaxhighlight lang="javascript"> | ||
| سطر 56: | سطر 56: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | == | + | == مشكلة تداخل أسماء الدوال == |
| − | يتوجّب | + | يتوجّب أحيانًا استخدام ملحقات Bootstrap مع أطر عمل واجهة مستخدم أخرى. قد تتداخل في هذه الحالة مجالات الأسماء. إن حدث ذلك فيمكنك استدعاء التابع <code>.noConflict</code> في المُلحَق الذي تريد استعادة قيمته السابقة.<syntaxhighlight lang="javascript"> |
var bootstrapButton = $.fn.button.noConflict() // يرجع $.fn.button إلى القيمة المُسنَدة إليه سابقا | var bootstrapButton = $.fn.button.noConflict() // يرجع $.fn.button إلى القيمة المُسنَدة إليه سابقا | ||
$.fn.bootstrapBtn = bootstrapButton // يسند وظيفة Bootstrap إلى $().bootstrapBtn | $.fn.bootstrapBtn = bootstrapButton // يسند وظيفة Bootstrap إلى $().bootstrapBtn | ||
| سطر 63: | سطر 63: | ||
== أعداد الإصدارات == | == أعداد الإصدارات == | ||
| − | يمكن الوصول إلى إصدار كل مُلحَق من ملحَقات Bootstrap عن طريق الخاصيّة <code>VERSION</code> في مشيّد المُلحَق. | + | يمكن الوصول إلى إصدار كل مُلحَق من ملحَقات Bootstrap عن طريق الخاصيّة <code>VERSION</code> في مشيّد المُلحَق. للحصول مثلًا على إصدار [[Bootstrap/tooltips|ملحَق التلميحات tooltip]]:<syntaxhighlight lang="javascript"> |
$.fn.tooltip.Constructor.VERSION // => "4.0.0" | $.fn.tooltip.Constructor.VERSION // => "4.0.0" | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | == لا بدائل احتياطية في حال | + | == لا بدائل احتياطية في حال تعطيل JavaScript == |
| − | لا تتوفّر ملحقات Bootstrap على بدائل احتياطية | + | لا تتوفّر ملحقات Bootstrap على بدائل احتياطية للعمل عند تعطيل JavaScript. لتجربة مستخدم أفضل، استخدم <code><noscript></code> لتشرح للمستخدمين الوضع وكيف يمكنهم إعادة تفعيل JavaScript، أو استخدم بدائل احتياطية مخصَّصة. |
'''تنبيه: مكتبات طرف ثالث''' | '''تنبيه: مكتبات طرف ثالث''' | ||
| − | '''لا يدعم Bootstrap رسميا مكتبات [[JavaScript]] من طرف ثالث''' مثل Prototype أو jQuery UI. على الرغم من وجود التابع <code>.noConflict</code> والأحداث التابعة لفضاء أسماء؛ إلا أنه يمكن أن توجد مشاكل توافقية تتطلّب أن تجد لها | + | '''لا يدعم Bootstrap رسميا مكتبات [[JavaScript]] من طرف ثالث''' مثل Prototype أو jQuery UI. على الرغم من وجود التابع <code>.noConflict</code> والأحداث التابعة لفضاء أسماء؛ إلا أنه يمكن أن توجد مشاكل توافقية تتطلّب أن تجد لها حلًا بنفسك. |
== Util == | == Util == | ||
| − | تعتمد جميع ملفات [[JavaScript]] في Bootstrap على الملف <code>util.js</code> ويجب أن يُضمَّن إلى جانب بقية ملفات [[JavaScript]]. | + | تعتمد جميع ملفات [[JavaScript]] في Bootstrap على الملف <code>util.js</code> ويجب أن يُضمَّن إلى جانب بقية ملفات [[JavaScript]]. أما إذا كنت تستخدم النسخة المجمَّعة (أو المُصغَّرة) <code>bootstrap.js</code> فلا حاجة لتضمين الملف، إذ أنه موجود مسبقا. |
| − | يتضمّن <code>util.js</code> دوال خدمية ومساعدات أساسية لأحداث <code>transitionEnd</code> علاوة على مُحاكٍ | + | يتضمّن <code>util.js</code> دوال خدمية ومساعدات أساسية لأحداث <code>transitionEnd</code> علاوة على مُحاكٍ [[:تصنيف:CSS Transitions|لا]]<nowiki/>[[:تصنيف:CSS Transitions|نتقالات CSS]]. تستخدم بقية الملحقات هذا الملف للتحقّق من دعم انتقالات CSS والتقاط الانتقالات العالقة. |
| + | |||
| + | == مصادر == | ||
| + | * [https://getbootstrap.com/docs/4.0/getting-started/javascript/ صفحة JavaScript في توثيق Bootstrap]. | ||
[[تصنيف:Bootstrap]] | [[تصنيف:Bootstrap]] | ||
[[تصنيف:Bootstrap Getting Started]] | [[تصنيف:Bootstrap Getting Started]] | ||
مراجعة 04:26، 13 مارس 2018
أنعش Bootstrap بملحقات JavaScript الاختيارية المبنية على jQuery. احصل على معلومات عن كل ملحق، وخيارات البيانات وواجهة التطبيقات البرمجية API وأمور أخرى.
فردية أو مجمَّعة
يمكن تضمين ملحقات فرديَّا (باستخدام ملفات *.js مُفرَدة من مجلّد Bootstrap) أو تضمين جميع الملحقات دفعة واحدة بالملف bootstrap.js أو نسخته المصغَّرة bootstrap.min.js (لا تضمّن الاثنين معًا).
الاعتماديّات
تعتمد بعض المحلقات وعناصر CSS على ملحقات أخرى. تأكّد عند تضمين الملحقات فرديًّا من التحقّق من الاعتماديّات في التوثيقات. انتبه كذلك إلى أنَّ الملحقات جميعها تعتمد على jQuery (يعني هذا أنه يجب تضمين jQuery قبل ملفات الملحقات). راجع الملف package.json لرؤية إصدارات jQuery المدعومة.
تعتمد القوائم المنسدلة (Dropdowns)، والعناصر المنبثقة (Popovers)، والتلميحات (Tooltips) جميعها على Popper.js.
خاصيّات البيانات
يمكن تفعيل ملحقات Bootstrap كلّها تقريبا وإعدادهًا بواسطة HTML وحده عن طريق خاصيّات البيانات (data attributes، وهي طريقة مطوّري Bootstrap التي يفضّلونها على استخدام JavaScript). تأكّد من استخدام مجموعة واحدة فقط من خاصيّات البيانات على عنصُر معيَّن (مثلاً؛ لا يمكن إظهار تلميح وفتح مربعات الحوار [Modal] بنفس الزّر).
يُرغَب أحيانًا في تعطيل الوظيفة المذكورة أعلاه. إن كنت ترغب في تعطيل واجهة التطبيقات البرمجية الخاصّة بخاصيّات البيانات فيمكنك ذلك بفصل جميع الأحداث في مجال الأسماء data-api من المستند؛ على النحو التالي:
$(document).off('.data-api')
كما يمكنك بدلًا من ذلك استهداف ملحق محدَّد بذكر اسمه ضمن فضاء الأسماء data-api على النحو التالي:
$(document).off('.alert.data-api')
تنبيه: تأكّد من تخليص المحدّدات المخصَّصة مثل collapse:Example إن كنت تستخدمها، إذ أنها ستمرّ عبر jQuery.
الأحداث
يوفّر Bootstrap أحداثًا مخصَّصة لأغلب الإجراءات الفريدة للملحقات. تأتي هذه الأحداث عمومًا بصيغتيْن تُسمَّى الأولى بأفعال إنكليزية مصدرية (show) والثانية بأسماء مفعولة (shown). تُطلَق الصيغة الأولى عند بداية الحدث فيما تُطلَق الثانية بعد اكتمال الحدث.
توفّر جميع الأحداث التي تحمل أسماء بأفعال مصدرية قدرةً على استعمال التابع preventDefault() الذي يمنح إمكانية إيقاف الحدث قبل أن يبدأ. يؤدّي إرجاع القيمة false من مُعالج الأحداث (Event handler) إلى استدعاء التابع preventDefault() تلقائيًا.
$('#myModal').on('show.bs.modal', function (e) {
if (!data) return e.preventDefault() // يوقف إظهار نافذة شرطية
})
واجهة تطبيقات برمجية
يرى فريق Bootstrap أنه يجب أن يكون المبرمج قادرًا على استخدام جميع ملحقات Bootstrap ببساطة عن طريق واجهة برمجية API باستخدام JavaScript. جميع الواجهات البرمجية في Bootstrap هي توابع منفردة يمكن استدعاؤها بالتتالي وتُرجِع المجموعة التي نُفِّذت عليها الإجراءات:
$('.btn.danger').button('toggle').addClass('fat')
يجب أن تتلقّى جميع التوابع إما كائنَ خيارات اختياري، أو سلسلة محارف تستهدف تابعًا مخصوصًا، أو لا شيء (وفي هذه الحالة يُلجَأ للسلوك المبدئي للملحَق):
$('#myModal').modal() // تُستهَل نافذة شرطية بالخيارات المبدئية
$('#myModal').modal({ keyboard: false }) // تُستهَل نافذة شرطية بدون لوحة مفاتيح
$('#myModal').modal('show') // تُستهَل نافذة شرطية بالتابع show وتُعرض مباشرة
يقدّم كلّ مُلحَق دالةً بانيةً (Constructor) في الخاصيّة Constructor، مثلا $.fn.popover.Constructor. يمكنك الحصول على نسخة (Instance) مُلحَق مخصوصة من العنصُر مباشرة $('[rel="popover"]').data('popover').
الدوال غير المتزامنة والانتقالات
جميع توابع واجهة التطبيقات البرمجية غير متزامنة (Asynchronous) وتعود إلى المُستدعي مباشرة بعد بدء الانتقال ولكن قبل أن يكتمل.
يجب الإنصات إلى الحدث المُصاحب لاكتمال الانتقال إن كنت تريد تنفيذ إجراء بعد اكتمال الحدث.
$('#myCollapse').on('shown.bs.collapse', function (e) { // الإجراء المُراد تنفيذه بعد تمدّد المساحة القابلة للتقلّص })
علاوة على ذلك، يُتجاهل استدعاء تابع لا يزال في طور الانتقال.
$('#myCarousel').on('slid.bs.carousel', function (e) {
$('#myCarousel').carousel('2') // ستنزلق الشريحة 2 فور اكتمال الانتقال إلى الشريحة 1
})
$('#myCarousel').carousel('1') // يبدأ الانزلاق إلى الشريحة 1 ويعود إلى المُستدعي
$('#myCarousel').carousel('2') // !! سيُتجاهل، إذ أن الانتقال إلى الشريحة 1 لم يكتمل بعد
الإعدادات المبدئية
يمكن تعديل الإعدادات المبدئية لمُلحَق بتغيير كائن Constructor.Default الخاصّ بالمُلحَق:
$.fn.modal.Constructor.Default.keyboard = false // يغيّر القيمة المبدئية للخيار `keyboard` في الملحق modal إلى false
مشكلة تداخل أسماء الدوال
يتوجّب أحيانًا استخدام ملحقات Bootstrap مع أطر عمل واجهة مستخدم أخرى. قد تتداخل في هذه الحالة مجالات الأسماء. إن حدث ذلك فيمكنك استدعاء التابع .noConflict في المُلحَق الذي تريد استعادة قيمته السابقة.
var bootstrapButton = $.fn.button.noConflict() // يرجع $.fn.button إلى القيمة المُسنَدة إليه سابقا
$.fn.bootstrapBtn = bootstrapButton // يسند وظيفة Bootstrap إلى $().bootstrapBtn
أعداد الإصدارات
يمكن الوصول إلى إصدار كل مُلحَق من ملحَقات Bootstrap عن طريق الخاصيّة VERSION في مشيّد المُلحَق. للحصول مثلًا على إصدار ملحَق التلميحات tooltip:
$.fn.tooltip.Constructor.VERSION // => "4.0.0"
لا بدائل احتياطية في حال تعطيل JavaScript
لا تتوفّر ملحقات Bootstrap على بدائل احتياطية للعمل عند تعطيل JavaScript. لتجربة مستخدم أفضل، استخدم <noscript> لتشرح للمستخدمين الوضع وكيف يمكنهم إعادة تفعيل JavaScript، أو استخدم بدائل احتياطية مخصَّصة.
تنبيه: مكتبات طرف ثالث
لا يدعم Bootstrap رسميا مكتبات JavaScript من طرف ثالث مثل Prototype أو jQuery UI. على الرغم من وجود التابع .noConflict والأحداث التابعة لفضاء أسماء؛ إلا أنه يمكن أن توجد مشاكل توافقية تتطلّب أن تجد لها حلًا بنفسك.
Util
تعتمد جميع ملفات JavaScript في Bootstrap على الملف util.js ويجب أن يُضمَّن إلى جانب بقية ملفات JavaScript. أما إذا كنت تستخدم النسخة المجمَّعة (أو المُصغَّرة) bootstrap.js فلا حاجة لتضمين الملف، إذ أنه موجود مسبقا.
يتضمّن util.js دوال خدمية ومساعدات أساسية لأحداث transitionEnd علاوة على مُحاكٍ لانتقالات CSS. تستخدم بقية الملحقات هذا الملف للتحقّق من دعم انتقالات CSS والتقاط الانتقالات العالقة.