الفرق بين المراجعتين ل"Bootstrap/javascript"
ط (استبدال النص - '\[\[تصنيف:(.*)\]\]' ب'{{SUBPAGENAME}}') |
(4.5) |
||
سطر 5: | سطر 5: | ||
يمكن تضمين ملحقات فرديَّا (باستخدام ملفات js مُفرَدة من مجلّد <code>Bootstrap</code>) أو تضمين جميع الملحقات دفعة واحدة بالملف <code>bootstrap.js</code> أو نسخته المصغَّرة <code>bootstrap.min.js</code> (لا تضمّن الاثنين معًا). | يمكن تضمين ملحقات فرديَّا (باستخدام ملفات js مُفرَدة من مجلّد <code>Bootstrap</code>) أو تضمين جميع الملحقات دفعة واحدة بالملف <code>bootstrap.js</code> أو نسخته المصغَّرة <code>bootstrap.min.js</code> (لا تضمّن الاثنين معًا). | ||
== الاعتماديّات == | == الاعتماديّات == | ||
− | تعتمد بعض المحلقات وعناصر [[CSS]] على ملحقات أخرى. تأكّد عند تضمين الملحقات فرديًّا من التحقّق من الاعتماديّات في التوثيقات. انتبه كذلك إلى أنَّ '''الملحقات جميعها تعتمد على [[jQuery]]''' (يعني هذا أنه يجب تضمين [[jQuery]] قبل ملفات الملحقات). راجع الملف <code>package.json</code> لرؤية إصدارات [[jQuery]] المدعومة. | + | تعتمد بعض المحلقات وعناصر [[CSS]] على ملحقات أخرى. تأكّد عند تضمين الملحقات فرديًّا من التحقّق من الاعتماديّات في التوثيقات. انتبه كذلك إلى أنَّ '''الملحقات جميعها تعتمد على [[jQuery]]''' (يعني هذا أنه يجب تضمين [[jQuery]] قبل ملفات الملحقات). راجع الملف <code>[https://github.com/twbs/bootstrap/blob/v4.5.0/package.json package.json]</code> لرؤية إصدارات [[jQuery]] المدعومة. |
تعتمد [[Bootstrap/dropdowns|القوائم المنسدلة (Dropdowns)]]، [[Bootstrap/popovers|والعناصر المنبثقة (Popovers)]]، [[Bootstrap/tooltips|والتلميحات (Tooltips)]] جميعها على [https://popper.js.org/ Popper.js]. | تعتمد [[Bootstrap/dropdowns|القوائم المنسدلة (Dropdowns)]]، [[Bootstrap/popovers|والعناصر المنبثقة (Popovers)]]، [[Bootstrap/tooltips|والتلميحات (Tooltips)]] جميعها على [https://popper.js.org/ Popper.js]. | ||
سطر 16: | سطر 16: | ||
</syntaxhighlight>كما يمكنك بدلًا من ذلك استهداف ملحق محدَّد بذكر اسمه ضمن فضاء الأسماء <code>data-api</code> على النحو التالي:<syntaxhighlight lang="javascript"> | </syntaxhighlight>كما يمكنك بدلًا من ذلك استهداف ملحق محدَّد بذكر اسمه ضمن فضاء الأسماء <code>data-api</code> على النحو التالي:<syntaxhighlight lang="javascript"> | ||
$(document).off('.alert.data-api') | $(document).off('.alert.data-api') | ||
− | </syntaxhighlight> | + | </syntaxhighlight> |
+ | |||
+ | === تنبيه: المُحددات === | ||
+ | نستخدم للبحث في شجرة DOM حاليًا التوابع الأصلية <code>querySelector</code> و <code>querySelectorAll</code> لأنّ أداءها أحسن. لذا عليك استخدام محدّدات صالحة. إن أردت استخدام محددات خاصة، مثل <code>collapse:Example</code>، احرص على تهريبها. | ||
== الأحداث == | == الأحداث == | ||
سطر 40: | سطر 43: | ||
يجب الإنصات إلى الحدث المُصاحب لاكتمال الانتقال إن كنت تريد تنفيذ إجراء بعد اكتمال الحدث.<syntaxhighlight lang="javascript"> | يجب الإنصات إلى الحدث المُصاحب لاكتمال الانتقال إن كنت تريد تنفيذ إجراء بعد اكتمال الحدث.<syntaxhighlight lang="javascript"> | ||
− | $('#myCollapse').on('shown.bs.collapse', function (e) { // الإجراء المُراد تنفيذه بعد تمدّد المساحة القابلة للتقلّص }) | + | $('#myCollapse').on('shown.bs.collapse', function (e) { |
+ | // الإجراء المُراد تنفيذه بعد تمدّد المساحة القابلة للتقلّص | ||
+ | }) | ||
</syntaxhighlight>علاوة على ذلك، '''يُتجاهل استدعاء تابع لا يزال في طور الانتقال'''.<syntaxhighlight lang="javascript"> | </syntaxhighlight>علاوة على ذلك، '''يُتجاهل استدعاء تابع لا يزال في طور الانتقال'''.<syntaxhighlight lang="javascript"> | ||
$('#myCarousel').on('slid.bs.carousel', function (e) { | $('#myCarousel').on('slid.bs.carousel', function (e) { | ||
سطر 77: | سطر 82: | ||
تعتمد جميع ملفات [[JavaScript]] في Bootstrap على الملف <code>util.js</code> ويجب أن يُضمَّن إلى جانب بقية ملفات [[JavaScript]]. أما إذا كنت تستخدم النسخة المجمَّعة (أو المُصغَّرة) <code>bootstrap.js</code> فلا حاجة لتضمين الملف، إذ أنه موجود مسبقا. | تعتمد جميع ملفات [[JavaScript]] في Bootstrap على الملف <code>util.js</code> ويجب أن يُضمَّن إلى جانب بقية ملفات [[JavaScript]]. أما إذا كنت تستخدم النسخة المجمَّعة (أو المُصغَّرة) <code>bootstrap.js</code> فلا حاجة لتضمين الملف، إذ أنه موجود مسبقا. | ||
− | يتضمّن <code>util.js</code> دوال خدمية ومساعدات أساسية لأحداث <code> | + | يتضمّن <code>util.js</code> دوال خدمية ومساعدات أساسية لأحداث <code>transitionPopovers End</code> علاوة على مُحاكٍ [[:تصنيف:CSS Transitions|لا]]<nowiki/>[[:تصنيف:CSS Transitions|نتقالات CSS]]. تستخدم بقية الملحقات هذا الملف للتحقّق من دعم انتقالات CSS والتقاط الانتقالات العالقة. |
+ | |||
+ | == المصححات Sanitizers == | ||
+ | تستخدم تعتمد [[Bootstrap/popovers|والعناصر المنبثقة (Popovers)]]، [[Bootstrap/tooltips|والتلميحات (Tooltips)]] مصححات مٌضمّنة للتحقق من صحة الخيارات التي تقبل قيم مكتوبة بترميز HTML. | ||
+ | |||
+ | هذه هي قيمة <code>whiteList</code> الافتراضية:<syntaxhighlight lang="javascript"> | ||
+ | var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i | ||
+ | var DefaultWhitelist = { | ||
+ | // Global attributes allowed on any supplied element below. | ||
+ | '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN], | ||
+ | a: ['target', 'href', 'title', 'rel'], | ||
+ | area: [], | ||
+ | b: [], | ||
+ | br: [], | ||
+ | col: [], | ||
+ | code: [], | ||
+ | div: [], | ||
+ | em: [], | ||
+ | hr: [], | ||
+ | h1: [], | ||
+ | h2: [], | ||
+ | h3: [], | ||
+ | h4: [], | ||
+ | h5: [], | ||
+ | h6: [], | ||
+ | i: [], | ||
+ | img: ['src', 'srcset', 'alt', 'title', 'width', 'height'], | ||
+ | li: [], | ||
+ | ol: [], | ||
+ | p: [], | ||
+ | pre: [], | ||
+ | s: [], | ||
+ | small: [], | ||
+ | span: [], | ||
+ | sub: [], | ||
+ | sup: [], | ||
+ | strong: [], | ||
+ | u: [], | ||
+ | ul: [] | ||
+ | } | ||
+ | </syntaxhighlight>يمكنك إضافة قيم جديدة للائحة البيضاء الافتراضية عبر ما يلي:<syntaxhighlight lang="javascript"> | ||
+ | var myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList | ||
+ | |||
+ | // لإتاحة عناصر الجدول | ||
+ | myDefaultWhiteList.table = [] | ||
+ | |||
+ | // data-option وسمات td للسماح بعناصر | ||
+ | myDefaultWhiteList.td = ['data-option'] | ||
+ | |||
+ | // يمكنك إضافة تعبير نمطي مخصص لتصحيح السمات | ||
+ | var myCustomRegex = /^data-my-app-[\w-]+/ | ||
+ | myDefaultWhiteList['*'].push(myCustomRegex) | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | يمكنك تجاوز المصحح عبر كتابة مايلي:<syntaxhighlight lang="javascript"> | ||
+ | $('#yourTooltip').tooltip({ | ||
+ | sanitizeFn: function (content) { | ||
+ | return DOMPurify.sanitize(content) | ||
+ | } | ||
+ | }) | ||
+ | </syntaxhighlight> | ||
== مصادر == | == مصادر == | ||
− | * [https://getbootstrap.com/docs/4. | + | * [https://getbootstrap.com/docs/4.5/getting-started/javascript/ صفحة JavaScript في توثيق Bootstrap]. |
[[تصنيف:Bootstrap|{{SUBPAGENAME}}]] | [[تصنيف:Bootstrap|{{SUBPAGENAME}}]] | ||
[[تصنيف:Bootstrap Getting Started|{{SUBPAGENAME}}]] | [[تصنيف:Bootstrap Getting Started|{{SUBPAGENAME}}]] |
المراجعة الحالية بتاريخ 07:18، 12 يوليو 2020
أنعش 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')
تنبيه: المُحددات
نستخدم للبحث في شجرة DOM حاليًا التوابع الأصلية querySelector
و querySelectorAll
لأنّ أداءها أحسن. لذا عليك استخدام محدّدات صالحة. إن أردت استخدام محددات خاصة، مثل collapse:Example
، احرص على تهريبها.
الأحداث
يوفّر 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
دوال خدمية ومساعدات أساسية لأحداث transitionPopovers End
علاوة على مُحاكٍ لانتقالات CSS. تستخدم بقية الملحقات هذا الملف للتحقّق من دعم انتقالات CSS والتقاط الانتقالات العالقة.
المصححات Sanitizers
تستخدم تعتمد والعناصر المنبثقة (Popovers)، والتلميحات (Tooltips) مصححات مٌضمّنة للتحقق من صحة الخيارات التي تقبل قيم مكتوبة بترميز HTML.
هذه هي قيمة whiteList
الافتراضية:
var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var DefaultWhitelist = {
// Global attributes allowed on any supplied element below.
'*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
a: ['target', 'href', 'title', 'rel'],
area: [],
b: [],
br: [],
col: [],
code: [],
div: [],
em: [],
hr: [],
h1: [],
h2: [],
h3: [],
h4: [],
h5: [],
h6: [],
i: [],
img: ['src', 'srcset', 'alt', 'title', 'width', 'height'],
li: [],
ol: [],
p: [],
pre: [],
s: [],
small: [],
span: [],
sub: [],
sup: [],
strong: [],
u: [],
ul: []
}
يمكنك إضافة قيم جديدة للائحة البيضاء الافتراضية عبر ما يلي:
var myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList
// لإتاحة عناصر الجدول
myDefaultWhiteList.table = []
// data-option وسمات td للسماح بعناصر
myDefaultWhiteList.td = ['data-option']
// يمكنك إضافة تعبير نمطي مخصص لتصحيح السمات
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultWhiteList['*'].push(myCustomRegex)
يمكنك تجاوز المصحح عبر كتابة مايلي:
$('#yourTooltip').tooltip({
sanitizeFn: function (content) {
return DOMPurify.sanitize(content)
}
})