الفرق بين المراجعتين ل"Bootstrap/popovers"
اذهب إلى التنقل
اذهب إلى البحث
مثال: استخدام الخيار
| سطر 3: | سطر 3: | ||
== نظرة عامّة == | == نظرة عامّة == | ||
في ما يلي أمور ينبغي إدراكها قبل البدء في استخدام مكوِّن العناصر المنبثقة الذي يوفّره Bootstrap: | في ما يلي أمور ينبغي إدراكها قبل البدء في استخدام مكوِّن العناصر المنبثقة الذي يوفّره Bootstrap: | ||
| − | * تعتمد العناصر المنبثقة على مكتبة [https://popper.js.org | + | * تعتمد العناصر المنبثقة على مكتبة [https://popper.js.org Popper.js] في تموضعها. لذا يجب - من أجل أن تعمل هذه العناصر - تضمين [https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js popper.min.js] قبل <code>bootstrap.js</code> أو استخدام <code>bootstrap.bundle.min.js</code> أو <code>bootstrap.bundle.js</code> الذين يتضمّنان Popper.js. |
* تعتمد العناصر المنبثقة على مُلحَق التلميحات. | * تعتمد العناصر المنبثقة على مُلحَق التلميحات. | ||
* انتبه إنْ كنت تبني JavaScript من الملفّات المصدريّة لإطار العمل Bootstrap إلى أنّه يتطلّب [[Bootstrap/javascript#Util |الملف <code>util.js</code>]] | * انتبه إنْ كنت تبني JavaScript من الملفّات المصدريّة لإطار العمل Bootstrap إلى أنّه يتطلّب [[Bootstrap/javascript#Util |الملف <code>util.js</code>]] | ||
| − | * العناصر المنبثقة اختيّاريّة - لأسباب تتعلّق بالأداء، و'''يجب بالتالي | + | * العناصر المنبثقة اختيّاريّة - لأسباب تتعلّق بالأداء، و'''يجب بالتالي تهيئتها (initialize) يدويّا'''. |
| − | * | + | * لن تظهر عناصر منبثقة أبدًا في قيم <code>title</code> و<code>content</code> الفارغة. |
| − | * حدّد القيمة <code>container: 'body'</code> لتجنّب مشاكل في العرض في المكوِّنات الأكثر تعقيدًا (مثل مجموعات الإدخال، مجموعات الأزرار، ...إلخ). | + | * حدّد القيمة <code>container: 'body'</code> لتجنّب مشاكل في العرض في المكوِّنات الأكثر تعقيدًا (مثل مجموعات الإدخال، مجموعات الأزرار، ...إلخ.). |
* لن تعمل العناصر المنبثقة على العناصر المخفيّة. | * لن تعمل العناصر المنبثقة على العناصر المخفيّة. | ||
* يجب ابتداء العناصر المنبثقة على العنصُر المُغلِّف عند استهداف عناصر تطبِّق الخاصيّة <code>disabled</code> أو الصنف <code>.disabled</code>. | * يجب ابتداء العناصر المنبثقة على العنصُر المُغلِّف عند استهداف عناصر تطبِّق الخاصيّة <code>disabled</code> أو الصنف <code>.disabled</code>. | ||
| − | * تتوسّط العناصر المنبثقة عند ابتدائها من روابط تلتفّ على أسطر متعدّدة تتوسّط العرض الكامل للرابط. استخدم الخاصيّة <code>white-space: nowrap;</code> على الرابط <code><a></code> لتفادي هذا الأمر. | + | * تتوسّط العناصر المنبثقة عند ابتدائها من روابط تلتفّ على أسطر متعدّدة تتوسّط العرض الكامل للرابط. استخدم الخاصيّة <code>[[CSS/white-space|white-space]]: nowrap;</code> على الرابط <code>[[HTML/a|<a>]]</code> لتفادي هذا الأمر. |
* يجب إخفاء العناصر المنبثقة حتى يتسنّى حذفُ العناصر المتعلّقة بها من كائن المستند DOM. | * يجب إخفاء العناصر المنبثقة حتى يتسنّى حذفُ العناصر المتعلّقة بها من كائن المستند DOM. | ||
واصل القراءة لأمثلة عن كيفيّة عمل العناصر المنبثقة. | واصل القراءة لأمثلة عن كيفيّة عمل العناصر المنبثقة. | ||
| − | == مثال: تفعيل العناصر المنبثقة في | + | == مثال: تفعيل العناصر المنبثقة في كل مكان == |
| − | إحدى | + | إحدى طرائق تمهيد (initialization) جميع العناصر المنبثقة في صفحة هي تحديدها باستخدام قيمة <code>data-toggle</code> الخاصّة بها (<code>data-toggle="popover"</code>). |
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
$(function () { | $(function () { | ||
| سطر 22: | سطر 22: | ||
}) | }) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | == مثال: استخدام | + | == مثال: استخدام الخيار <code>container</code> == |
عندما تكون هناك أنماط على عنصُر أب تتداخل مع عنصُر منبثق فستحتاج لتحديد حاويّة (<code>container</code>) مُخصَّصة بحيث تظهر شفرة HTML الخاصّة بالعنصُر المنبثق داخل الحاويّة. | عندما تكون هناك أنماط على عنصُر أب تتداخل مع عنصُر منبثق فستحتاج لتحديد حاويّة (<code>container</code>) مُخصَّصة بحيث تظهر شفرة HTML الخاصّة بالعنصُر المنبثق داخل الحاويّة. | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
| سطر 35: | سطر 35: | ||
<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="وصف محتوى العنصُر">انقر لإظهار العنصُر المنبثق أو إخفائه</button> | <button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="وصف محتوى العنصُر">انقر لإظهار العنصُر المنبثق أو إخفائه</button> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | === | + | === الاتجاهات الأربع === |
| − | + | تتوافر أربع خيّارات لمحاذاة العنصُر المبثق: في الأعلى، وإلى اليمين، وفي الأسفل وإلى اليسار. | |
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="وصف العنصُر"> | <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="وصف العنصُر"> | ||
| سطر 54: | سطر 54: | ||
</button> | </button> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | === الإخفاء عند النقر خارج | + | === الإخفاء عند النقر خارج العنصر === |
استخدم الخاصيّة <code>focus</code> لإخفاء العنصُر المنبثق عند نقر المستخدم على عنصُر مغاير للذي تسبّب في إظهار العنصُر المنبثق. | استخدم الخاصيّة <code>focus</code> لإخفاء العنصُر المنبثق عند نقر المستخدم على عنصُر مغاير للذي تسبّب في إظهار العنصُر المنبثق. | ||
| − | '''تنبيه:''' تتطلّب هذه الميزة لكي تعمل على مختلف المنصّات والمتصفّحات استخدام الوسم <code><a></code> | + | |
| + | '''تنبيه:''' تتطلّب هذه الميزة لكي تعمل على مختلف المنصّات والمتصفّحات استخدام الوسم <code>[[HTML/a|<a>]]</code> وليس العنصر <code>[[HTML/button|<button>]]</code>، كما يجب أن تضمِّن الخاصيّة <code>[[HTML/Global Attributes#tabindex|tabindex]]</code>. | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="وصف العنصُر">عنصُر منبثق يمكن إخفاؤه</a> | <a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="وصف العنصُر">عنصُر منبثق يمكن إخفاؤه</a> | ||
| سطر 65: | سطر 66: | ||
}) | }) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | === العناصر | + | === العناصر المعطلة === |
| − | لا تعدّ العناصر التي تُطبَّق عليها الخاصيّة <code>disabled</code> تفاعليّة، ممّا يعني أنّ المستخدمين لا يستطيعون الحومان فوقها أو النقر عليها لإظهار عنصُر منبثق (أو تلميح). الحلّ البديل هو إظهار عنصُر منبثق من عنصُر مغلِّف (<code><div></code> أو <code><span></code>) وإبطال أحداث المؤشِّر (<code>pointer-events</code>) على العنصُر المُعطَّل. | + | لا تعدّ العناصر التي تُطبَّق عليها الخاصيّة <code>disabled</code> تفاعليّة، ممّا يعني أنّ المستخدمين لا يستطيعون الحومان فوقها أو النقر عليها لإظهار عنصُر منبثق (أو تلميح). الحلّ البديل هو إظهار عنصُر منبثق من عنصُر مغلِّف (<code>[[HTML/div|<div>]]</code> أو <code>[[HTML/span|<span>]]</code>) وإبطال أحداث المؤشِّر (<code>pointer-events</code>) على العنصُر المُعطَّل. |
| + | |||
يمكن كذلك استخدام الخاصيّة <code>data-trigger="hover"</code> لابتداء العنصُر المنبثق مباشرةً إذْ قد لا يتوقّع الزائر أنّ بإمكانه ''النقر'' على عنصُر مُعطَّل. | يمكن كذلك استخدام الخاصيّة <code>data-trigger="hover"</code> لابتداء العنصُر المنبثق مباشرةً إذْ قد لا يتوقّع الزائر أنّ بإمكانه ''النقر'' على عنصُر مُعطَّل. | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
| سطر 74: | سطر 76: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | == استخدام | + | == استخدام ملحق JavaScript == |
تفعيل العناصر المنبثقة باستخدام شفرة JavaScript: | تفعيل العناصر المنبثقة باستخدام شفرة JavaScript: | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
$('#example').popover(options) | $('#example').popover(options) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | === | + | === الخيارات === |
| − | يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة <code>data-</code> (مثلًا <code>data-animation=""</code> للخيّار <code>animation</code>) عند التمرير عبر خاصيّات البيانات. | + | يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق [[JavaScript]]. ألحق اسم الخيّار بالكلمة <code>data-</code> (مثلًا <code>data-animation=""</code> للخيّار <code>animation</code>) عند التمرير عبر خاصيّات البيانات. |
| − | {|class="wikitable" | + | {| class="wikitable" |
!الاسم | !الاسم | ||
!النوع | !النوع | ||
| سطر 87: | سطر 89: | ||
!الوصف | !الوصف | ||
|- | |- | ||
| − | |animation (التحريك) | + | |<code>animation</code> (التحريك) |
|قيمة منطقيّة | |قيمة منطقيّة | ||
| − | |true | + | |<code>true</code> |
|تطبيق تأثير الخفوت في CSS على العنصُر المنبثق | |تطبيق تأثير الخفوت في CSS على العنصُر المنبثق | ||
|- | |- | ||
| − | |container (الحاويّة) | + | |<code>container</code> (الحاويّة) |
| − | |سلسلة محارف | عنصُر | false | + | | سلسلة محارف |<nowiki> عنصُر | false</nowiki> |
| − | |false | + | |<code>false</code> |
| | | | ||
إلحاق العنصُر المنبثق بالعنصُر المخصوص. مثال: <code>container: 'body'</code>. هذا الخيّار مفيد جدًّا، إذ يمكّنك من وضع العنصُر المنبثق قرب العنصُر الذي يتعلّق به، ممّا يمنع العنصُر المنبثق من الابتعاد أثناء تغيير قياس النافذة. | إلحاق العنصُر المنبثق بالعنصُر المخصوص. مثال: <code>container: 'body'</code>. هذا الخيّار مفيد جدًّا، إذ يمكّنك من وضع العنصُر المنبثق قرب العنصُر الذي يتعلّق به، ممّا يمنع العنصُر المنبثق من الابتعاد أثناء تغيير قياس النافذة. | ||
|- | |- | ||
| − | |content (المحتوى) | + | |<code>content</code> (المحتوى) |
| − | |سلسلة محارف | عنصُر | دالّة | + | | سلسلة محارف |<nowiki> عنصُر | دالّة</nowiki> |
| − | |سلسلة | + | |سلسلة نصية فارغة |
| | | | ||
تأخذ القيمة المبدئيّة إن لم تكن الخاصيّة <code>data-content</code> موجودة على العنصُر المنبثق. | تأخذ القيمة المبدئيّة إن لم تكن الخاصيّة <code>data-content</code> موجودة على العنصُر المنبثق. | ||
| − | عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر <code>this</code>. | + | |
| + | عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر <code>[[JavaScript/this|this]]</code>. | ||
|- | |- | ||
| − | |delay (تأخير) | + | |<code>delay</code> (تأخير) |
| − | |عدد | كائن | + | | عدد | كائن |
|0 | |0 | ||
| | | | ||
تأخير إظهار أو إخفاء العنصُر المنبثق (بالميلّي ثانيّة). لا ينطبق على العناصر المنبثقة المُظهرة يدويّا. | تأخير إظهار أو إخفاء العنصُر المنبثق (بالميلّي ثانيّة). لا ينطبق على العناصر المنبثقة المُظهرة يدويّا. | ||
| + | |||
عند تمرير عدد فإنّ التأخير يُطبَّق على الإظهار (<code>show</code>) والإخفاء (<code>hide</code>) كليهما. | عند تمرير عدد فإنّ التأخير يُطبَّق على الإظهار (<code>show</code>) والإخفاء (<code>hide</code>) كليهما. | ||
| + | |||
بنية الكائن هي كالتالي: | بنية الكائن هي كالتالي: | ||
| + | |||
<code>delay: { "show": 500, "hide": 100 }</code> | <code>delay: { "show": 500, "hide": 100 }</code> | ||
|- | |- | ||
| − | |html | + | |<code>html</code> |
|قيمة منطقيّة | |قيمة منطقيّة | ||
| − | |false | + | |<code>false</code> |
|إدراج وسوم HTML ضمن العنصُر المنبثق. تُستخدَم الدالّة <code>text</code> في jQuery لإدراج المحتوى في كائن المستند إذا كانت قيمة الخيّار <code>false</code>. استخدم نصّا إنْ كنت نصا بسيطًا إنْ كنت تخشى من هجمات XSS. | |إدراج وسوم HTML ضمن العنصُر المنبثق. تُستخدَم الدالّة <code>text</code> في jQuery لإدراج المحتوى في كائن المستند إذا كانت قيمة الخيّار <code>false</code>. استخدم نصّا إنْ كنت نصا بسيطًا إنْ كنت تخشى من هجمات XSS. | ||
|- | |- | ||
| − | |placement (التموضع) | + | |<code>placement</code> (التموضع) |
| − | |سلسة محارف | دالّة | + | | سلسة محارف | دالّة |
|<code>'right'</code> | |<code>'right'</code> | ||
| | | | ||
| − | تموضع العنصُر المنبثق: | + | تموضع العنصُر المنبثق: <code>auto</code> (تلقائي) | <code>top</code> (أعلى) | <code>bottom</code> (أسفل) | <code>left</code> (يسار) | <code>right</code> (يمين).<br>يُعاد توجيه العنصُر المنبثق تلقائيَّا عند اختيّار التموضع التلقائي (<code>auto</code>). |
| − | عند استخدام دالّة لتحديد التموضع فإنّ المُعطَى الأوّل الذي يُمرّر لها أثناء استدعائها هو مكان العنصُر المنبثق في كائن المستنَد والمُعطَى الثاني هو مكان العنصُر الذي تسبّب في إظهار العنصُر المنبثق. يُعيَّن سياق المتغيّر <code>this</code> إلى العنصُر المنبثق. | + | |
| + | عند استخدام دالّة لتحديد التموضع فإنّ المُعطَى الأوّل الذي يُمرّر لها أثناء استدعائها هو مكان العنصُر المنبثق في كائن المستنَد والمُعطَى الثاني هو مكان العنصُر الذي تسبّب في إظهار العنصُر المنبثق. يُعيَّن سياق المتغيّر <code>[[JavaScript/this|this]]</code> إلى العنصُر المنبثق. | ||
|- | |- | ||
| − | |selector (المُحدِّد) | + | |<code>selector</code> (المُحدِّد) |
| − | |سلسلة محارف | false | + | | سلسلة محارف | false |
| − | |false | + | |<code>false</code> |
| − | |تُفوّض كائنات العناصر المنبثقة إلى الأهداف المُحدّدة إذا كان هناك مُحدِد مُمرّر. يُستخدَم هذا الخيّار عمليًّا لتفعيل محتوى HTML ديناميكيّ لإضافة عناصر منبثقة. انظر [https://github.com/twbs/bootstrap/issues/4215 هنا] و[https://jsbin.com/zopod/1/edit | + | |تُفوّض كائنات العناصر المنبثقة إلى الأهداف المُحدّدة إذا كان هناك مُحدِد مُمرّر. يُستخدَم هذا الخيّار عمليًّا لتفعيل محتوى HTML ديناميكيّ لإضافة عناصر منبثقة. انظر [https://github.com/twbs/bootstrap/issues/4215 هنا] و[https://jsbin.com/zopod/1/edit هذا المثال المفيد]. |
|- | |- | ||
| − | |template (قالب) | + | |<code>template</code> (قالب) |
|سلسلة محارف | |سلسلة محارف | ||
| − | |'<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>' | + | |<code>'<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'</code> |
| | | | ||
| − | شفرة HTML قاعديّة للاستخدام أثناء إنشاء العنصُر المنبثق | + | شفرة HTML قاعديّة للاستخدام أثناء إنشاء العنصُر المنبثق. |
| + | |||
يُحقَن عنوان العنصُر المنبثق (<code>title</code>) في الصنف (<code>.popover-header</code>). | يُحقَن عنوان العنصُر المنبثق (<code>title</code>) في الصنف (<code>.popover-header</code>). | ||
| − | + | ||
| − | تصبح قيمة <code>.arrow</code> قيمة الخاصيّة <code>arrow</code> في العنصُر المنبثق. | + | يُحقَن مُحتوى العنصُر المنبثق (<code>content</code>) في الصنف <code>.popover-body</code>. |
| − | يجب أن يحوي العنصُر المغلِّف الأعلى الصنف <code>.popover</code> . | + | |
| + | تصبح قيمة <code>.arrow</code> قيمة الخاصيّة <code>arrow</code> في العنصُر المنبثق. | ||
| + | |||
| + | يجب أن يحوي العنصُر المغلِّف الأعلى الصنف <code>.popover</code> . | ||
|- | |- | ||
| − | |title (العنوان) | + | |<code>title</code> (العنوان) |
| − | |سلسلة محارف | عنصُر | دالّة | + | | سلسلة محارف |<nowiki> عنصُر | دالّة</nowiki> |
| − | | | + | | |
| | | | ||
قيمة العنوان المبدئيّة إنْ لم تكن الخاصيّة <code>title</code> موجودة في العنصُر المنبثق | قيمة العنوان المبدئيّة إنْ لم تكن الخاصيّة <code>title</code> موجودة في العنصُر المنبثق | ||
| − | عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر this. | + | |
| + | عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر <code>[[JavaScript/this|this]]</code>. | ||
|- | |- | ||
| − | |trigger (التفعيل) | + | |<code>trigger</code> (التفعيل) |
|سلسلة محارف | |سلسلة محارف | ||
|<code>'click'</code> | |<code>'click'</code> | ||
| − | |كيفيّة تفعيل العنصُر المنبثق: click (النقر) | hover (الحومان) | focus (تركيز المؤشّر) | manual (يدويًّا). يمكن تعيين أكثر من طريقة، افصل بينها بمسافة. لا يمكن الجمع بين التفعيل يدويًّا manual وأي طريقة أخرى. | + | | كيفيّة تفعيل العنصُر المنبثق: click (النقر) | <code>click</code><nowiki> (النقر) | </nowiki><code>hover</code><nowiki> (الحومان) | </nowiki><code>focus</code><nowiki> (تركيز المؤشّر) | </nowiki><code>manual</code> (يدويًّا). يمكن تعيين أكثر من طريقة، افصل بينها بمسافة. لا يمكن الجمع بين التفعيل يدويًّا <code>manual</code> وأي طريقة أخرى. |
|- | |- | ||
| − | |offset (الانزياح) | + | |<code>offset</code> (الانزياح) |
| − | |عدد | سلسلة محارف | + | | عدد | سلسلة محارف |
| − | |0 | + | |<code>0</code> |
|انزيّاح العنصُر المنبثق عن العنصُر المستهدَف. راجع [https://popper.js.org/popper-documentation.html#modifiers..offset.offset توثيق Offset في Popper.js]. | |انزيّاح العنصُر المنبثق عن العنصُر المستهدَف. راجع [https://popper.js.org/popper-documentation.html#modifiers..offset.offset توثيق Offset في Popper.js]. | ||
|- | |- | ||
| − | |fallbackPlacement (موضع التراجع) | + | |<code>fallbackPlacement</code> (موضع التراجع) |
| − | |سلسلة محارف | مصفوفة | + | | سلسلة محارف | مصفوفة |
|<code>'flip'</code> | |<code>'flip'</code> | ||
|يسمح بتحديد الموضع الذي سيختاره Popper.js عند التراجع Fallback. راجع [https://popper.js.org/popper-documentation.html#modifiers..flip.behavior توثيق Popper.js] للمزيد من المعلومات. | |يسمح بتحديد الموضع الذي سيختاره Popper.js عند التراجع Fallback. راجع [https://popper.js.org/popper-documentation.html#modifiers..flip.behavior توثيق Popper.js] للمزيد من المعلومات. | ||
|- | |- | ||
| − | |boundary (حدود) | + | |<code>boundary</code> (حدود) |
| − | |سلسلة محارف | عنصُر | + | | سلسلة محارف | عنصُر |
|<code>'scrollParent'</code> | |<code>'scrollParent'</code> | ||
|حدود قيد طفح Overflow العنصُر المنبثق. يقبل القيم <code>'viewport'</code> (إطار العرض)، أو<code>'window'</code> (نافذة)، أو <code>'scrollParent'</code> (عنصُر أب يقبل التمرير) أو عنصُر HTML (فقط عند استخدام JavaScript). [https://popper.js.org/popper-documentation.html#modifiers..preventOverflow.boundariesElement راجع توثيق Popper.js] للمزيد من المعلومات. | |حدود قيد طفح Overflow العنصُر المنبثق. يقبل القيم <code>'viewport'</code> (إطار العرض)، أو<code>'window'</code> (نافذة)، أو <code>'scrollParent'</code> (عنصُر أب يقبل التمرير) أو عنصُر HTML (فقط عند استخدام JavaScript). [https://popper.js.org/popper-documentation.html#modifiers..preventOverflow.boundariesElement راجع توثيق Popper.js] للمزيد من المعلومات. | ||
| سطر 173: | سطر 185: | ||
=== التوابع === | === التوابع === | ||
'''تنبيه: التوابع غير المتزامنة والانتقالات''' | '''تنبيه: التوابع غير المتزامنة والانتقالات''' | ||
| + | |||
توابع واجهة التطبيقات جميعها غير متزامنة وتشغّل انتقالا. تعود هذه التوابع لشفرة الاستدعاء مباشرةً بعد بدء الانتقال، لكن قبل أن ينتهي. علاوةً على ذلك، يُتجاهل استدعاء تابع على مكوِّن في طور الانتقال. | توابع واجهة التطبيقات جميعها غير متزامنة وتشغّل انتقالا. تعود هذه التوابع لشفرة الاستدعاء مباشرةً بعد بدء الانتقال، لكن قبل أن ينتهي. علاوةً على ذلك، يُتجاهل استدعاء تابع على مكوِّن في طور الانتقال. | ||
| − | ==== <code>$().popover(options)</code> ==== | + | ==== <code>$().popover(options)</code> ==== |
يمهِّد العناصر المنبثقة المتعلّقة بمجموعة من العناصر. | يمهِّد العناصر المنبثقة المتعلّقة بمجموعة من العناصر. | ||
| − | ==== <code>.popover('show')</code> ==== | + | ==== <code>.popover('show')</code> ==== |
يُظهر العنصُر المنبثق المتعلِّق بعنصُر. '''يعود إلى المُستدعِي قبل أن يُعرَض العنصُر المنبثق فعليًّا''' (أي قبل وقوع الحدث <code>shown.bs.popover</code>). يُعدّ استخدام هذا التابع عرضًا يدويًّا للعنصُر المنبثق. لا تُعرَض العناصر المنبثقة ذات العنوان والمحتوى الفارغيْن (طول سلسلة المحارف يساوي صفرا). | يُظهر العنصُر المنبثق المتعلِّق بعنصُر. '''يعود إلى المُستدعِي قبل أن يُعرَض العنصُر المنبثق فعليًّا''' (أي قبل وقوع الحدث <code>shown.bs.popover</code>). يُعدّ استخدام هذا التابع عرضًا يدويًّا للعنصُر المنبثق. لا تُعرَض العناصر المنبثقة ذات العنوان والمحتوى الفارغيْن (طول سلسلة المحارف يساوي صفرا). | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
$('#element').popover('show') | $('#element').popover('show') | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | ==== <code>.popover('hide')</code> ==== | + | ==== <code>.popover('hide')</code> ==== |
يخفي العنصُر المنبثق المتعلِّق بعنصُر. '''يعود إلى المُستدعِي قبل أن يُخفَى العنصُر المنبثق فعليًّا''' (أي قبل وقوع الحدث <code>hidden.bs.popover</code>). يُعدّ استخدام هذا التابع إخفاءً يدويًّا للعنصُر المنبثق. | يخفي العنصُر المنبثق المتعلِّق بعنصُر. '''يعود إلى المُستدعِي قبل أن يُخفَى العنصُر المنبثق فعليًّا''' (أي قبل وقوع الحدث <code>hidden.bs.popover</code>). يُعدّ استخدام هذا التابع إخفاءً يدويًّا للعنصُر المنبثق. | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
$('#element').popover('hide') | $('#element').popover('hide') | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | ==== <code>.popover('toggle')</code> ==== | + | ==== <code>.popover('toggle')</code> ==== |
يبدّل حالة العنصُر المنبثق المتعلِّق بعنصُر (يُخفيه عندما ما يكون ظاهرًا، والعكس). '''يعود إلى المُستدعِي قبل أن يُظهَر العنصُر المنبثق أو يُخفَى فعليًّا''' (أي قبل وقوع الحدث <code>hidden.bs.popover</code> أو <code>shown.bs.popover</code>). يُعدّ استخدام هذا التابع إخفاءً يدويًّا للعنصُر المنبثق. | يبدّل حالة العنصُر المنبثق المتعلِّق بعنصُر (يُخفيه عندما ما يكون ظاهرًا، والعكس). '''يعود إلى المُستدعِي قبل أن يُظهَر العنصُر المنبثق أو يُخفَى فعليًّا''' (أي قبل وقوع الحدث <code>hidden.bs.popover</code> أو <code>shown.bs.popover</code>). يُعدّ استخدام هذا التابع إخفاءً يدويًّا للعنصُر المنبثق. | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
$('#element').popover('toggle') | $('#element').popover('toggle') | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | ==== <code>.popover('dispose')</code> ==== | + | ==== <code>.popover('dispose')</code> ==== |
يخفي العنصُر المنبثق ويحذفه. لا يمكن حذف العناصر المنبثقة التي تستخدم التفويض (أي التي أُنشِئت باستخدام المُحدِّد <code>selector</code>) فرديًّا من العناصر الأبناء. | يخفي العنصُر المنبثق ويحذفه. لا يمكن حذف العناصر المنبثقة التي تستخدم التفويض (أي التي أُنشِئت باستخدام المُحدِّد <code>selector</code>) فرديًّا من العناصر الأبناء. | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
$('#element').popover('dispose') | $('#element').popover('dispose') | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | ==== <code>.popover('enable')</code> ==== | + | ==== <code>.popover('enable')</code> ==== |
يمنح العنصُر المنبثق المتعلِّق بعنصُر قابليّة العرض. '''تُفعَّل العناصر المنبثقة مبدئيّا'''. | يمنح العنصُر المنبثق المتعلِّق بعنصُر قابليّة العرض. '''تُفعَّل العناصر المنبثقة مبدئيّا'''. | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
$('#element').popover('enable') | $('#element').popover('enable') | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | ==== <code>.popover('disable')</code> ==== | + | ==== <code>.popover('disable')</code> ==== |
يحذف قابليّة العرض من العنصُر المنبثق المتعلِّق بعنصُر. لن يمكن عرض العنصُر المنبثق بعدها إلّا إذا أعيد تفعيل قابليّة عرضه. | يحذف قابليّة العرض من العنصُر المنبثق المتعلِّق بعنصُر. لن يمكن عرض العنصُر المنبثق بعدها إلّا إذا أعيد تفعيل قابليّة عرضه. | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
$('#element').popover('disable') | $('#element').popover('disable') | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | ==== <code>.popover('toggleEnabled')</code> ==== | + | ==== <code>.popover('toggleEnabled')</code> ==== |
يبدّل حالة قابليّة العرض الخاصّة بالعنصُر المنبثق المتعلِّق بعنصُر. | يبدّل حالة قابليّة العرض الخاصّة بالعنصُر المنبثق المتعلِّق بعنصُر. | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
$('#element').popover('toggleEnabled') | $('#element').popover('toggleEnabled') | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | ==== <code>.popover('update')</code> ==== | + | ==== <code>.popover('update')</code> ==== |
يحدّث موضع العنصُر المنبثق المتعلِّق بعنصُر | يحدّث موضع العنصُر المنبثق المتعلِّق بعنصُر | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
| سطر 217: | سطر 230: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== الأحداث === | === الأحداث === | ||
| − | {|class="wikitable" | + | {| class="wikitable" |
!نوع الحدث | !نوع الحدث | ||
!الوصف | !الوصف | ||
| سطر 231: | سطر 244: | ||
|- | |- | ||
|<code>hidden.bs.popover</code> | |<code>hidden.bs.popover</code> | ||
| − | |يُطلَق هذا الحدث عندما يكتمل إخفاء العنصر المنبثق عن الزائر | + | |يُطلَق هذا الحدث عندما يكتمل إخفاء العنصر المنبثق عن الزائر (ينتظر اكتمال انتقالات CSS). |
|- | |- | ||
|<code>inserted.bs.popover</code> | |<code>inserted.bs.popover</code> | ||
| سطر 243: | سطر 256: | ||
}) | }) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | [[تصنيف:Bootstrap]][[تصنيف:Bootstrap components]] | + | |
| + | == مصادر == | ||
| + | * [https://getbootstrap.com/docs/4.0/components/popovers/ صفحة Popovers في توثيق Bootstrap]. | ||
| + | [[تصنيف:Bootstrap]] | ||
| + | [[تصنيف:Bootstrap components]] | ||
مراجعة 04:13، 14 أبريل 2018
استخدم العناصر المنبثقّة Popovers التي يوفّرها إطار العمل Bootstrap لإضافة تنسيقات وتأثيرات مماثلة لتلك الموجودة في iOS إلى صفحات ويب.
نظرة عامّة
في ما يلي أمور ينبغي إدراكها قبل البدء في استخدام مكوِّن العناصر المنبثقة الذي يوفّره Bootstrap:
- تعتمد العناصر المنبثقة على مكتبة Popper.js في تموضعها. لذا يجب - من أجل أن تعمل هذه العناصر - تضمين popper.min.js قبل
bootstrap.jsأو استخدامbootstrap.bundle.min.jsأوbootstrap.bundle.jsالذين يتضمّنان Popper.js. - تعتمد العناصر المنبثقة على مُلحَق التلميحات.
- انتبه إنْ كنت تبني JavaScript من الملفّات المصدريّة لإطار العمل Bootstrap إلى أنّه يتطلّب الملف
util.js - العناصر المنبثقة اختيّاريّة - لأسباب تتعلّق بالأداء، ويجب بالتالي تهيئتها (initialize) يدويّا.
- لن تظهر عناصر منبثقة أبدًا في قيم
titleوcontentالفارغة. - حدّد القيمة
container: 'body'لتجنّب مشاكل في العرض في المكوِّنات الأكثر تعقيدًا (مثل مجموعات الإدخال، مجموعات الأزرار، ...إلخ.). - لن تعمل العناصر المنبثقة على العناصر المخفيّة.
- يجب ابتداء العناصر المنبثقة على العنصُر المُغلِّف عند استهداف عناصر تطبِّق الخاصيّة
disabledأو الصنف.disabled. - تتوسّط العناصر المنبثقة عند ابتدائها من روابط تلتفّ على أسطر متعدّدة تتوسّط العرض الكامل للرابط. استخدم الخاصيّة
white-space: nowrap;على الرابط<a>لتفادي هذا الأمر. - يجب إخفاء العناصر المنبثقة حتى يتسنّى حذفُ العناصر المتعلّقة بها من كائن المستند DOM.
واصل القراءة لأمثلة عن كيفيّة عمل العناصر المنبثقة.
مثال: تفعيل العناصر المنبثقة في كل مكان
إحدى طرائق تمهيد (initialization) جميع العناصر المنبثقة في صفحة هي تحديدها باستخدام قيمة data-toggle الخاصّة بها (data-toggle="popover").
$(function () {
$('[data-toggle="popover"]').popover()
})
مثال: استخدام الخيار container
عندما تكون هناك أنماط على عنصُر أب تتداخل مع عنصُر منبثق فستحتاج لتحديد حاويّة (container) مُخصَّصة بحيث تظهر شفرة HTML الخاصّة بالعنصُر المنبثق داخل الحاويّة.
$(function () {
$('.example-popover').popover({
container: 'body'
})
})
مثال
<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="وصف محتوى العنصُر">انقر لإظهار العنصُر المنبثق أو إخفائه</button>
الاتجاهات الأربع
تتوافر أربع خيّارات لمحاذاة العنصُر المبثق: في الأعلى، وإلى اليمين، وفي الأسفل وإلى اليسار.
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="وصف العنصُر">
عنصُر منبثق إلى الأعلى
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="وصف العنصُر">
عنصُر منبثق إلى اليمين
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="وصف العنصُر">
عنصُر منبثق إلى الأسفل
</button>
<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="وصف العنصُر">
عنصُر منبثق إلى اليسار
</button>
الإخفاء عند النقر خارج العنصر
استخدم الخاصيّة focus لإخفاء العنصُر المنبثق عند نقر المستخدم على عنصُر مغاير للذي تسبّب في إظهار العنصُر المنبثق.
تنبيه: تتطلّب هذه الميزة لكي تعمل على مختلف المنصّات والمتصفّحات استخدام الوسم <a> وليس العنصر <button>، كما يجب أن تضمِّن الخاصيّة tabindex.
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="وصف العنصُر">عنصُر منبثق يمكن إخفاؤه</a>
$('.popover-dismiss').popover({
trigger: 'focus'
})
العناصر المعطلة
لا تعدّ العناصر التي تُطبَّق عليها الخاصيّة disabled تفاعليّة، ممّا يعني أنّ المستخدمين لا يستطيعون الحومان فوقها أو النقر عليها لإظهار عنصُر منبثق (أو تلميح). الحلّ البديل هو إظهار عنصُر منبثق من عنصُر مغلِّف (<div> أو <span>) وإبطال أحداث المؤشِّر (pointer-events) على العنصُر المُعطَّل.
يمكن كذلك استخدام الخاصيّة data-trigger="hover" لابتداء العنصُر المنبثق مباشرةً إذْ قد لا يتوقّع الزائر أنّ بإمكانه النقر على عنصُر مُعطَّل.
<span class="d-inline-block" data-toggle="popover" data-content="عنصُر منبثق">
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>زرّ مُعطَّل</button>
</span>
استخدام ملحق JavaScript
تفعيل العناصر المنبثقة باستخدام شفرة JavaScript:
$('#example').popover(options)
الخيارات
يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة data- (مثلًا data-animation="" للخيّار animation) عند التمرير عبر خاصيّات البيانات.
| الاسم | النوع | القيمة المبدئيّة | الوصف |
|---|---|---|---|
animation (التحريك)
|
قيمة منطقيّة | true
|
تطبيق تأثير الخفوت في CSS على العنصُر المنبثق |
container (الحاويّة)
|
عنصُر | false | false
|
إلحاق العنصُر المنبثق بالعنصُر المخصوص. مثال: |
content (المحتوى)
|
عنصُر | دالّة | سلسلة نصية فارغة |
تأخذ القيمة المبدئيّة إن لم تكن الخاصيّة عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر |
delay (تأخير)
|
كائن | 0 |
تأخير إظهار أو إخفاء العنصُر المنبثق (بالميلّي ثانيّة). لا ينطبق على العناصر المنبثقة المُظهرة يدويّا. عند تمرير عدد فإنّ التأخير يُطبَّق على الإظهار ( بنية الكائن هي كالتالي:
|
html
|
قيمة منطقيّة | false
|
إدراج وسوم HTML ضمن العنصُر المنبثق. تُستخدَم الدالّة text في jQuery لإدراج المحتوى في كائن المستند إذا كانت قيمة الخيّار false. استخدم نصّا إنْ كنت نصا بسيطًا إنْ كنت تخشى من هجمات XSS.
|
placement (التموضع)
|
دالّة | 'right'
|
تموضع العنصُر المنبثق: عند استخدام دالّة لتحديد التموضع فإنّ المُعطَى الأوّل الذي يُمرّر لها أثناء استدعائها هو مكان العنصُر المنبثق في كائن المستنَد والمُعطَى الثاني هو مكان العنصُر الذي تسبّب في إظهار العنصُر المنبثق. يُعيَّن سياق المتغيّر |
selector (المُحدِّد)
|
false | false
|
تُفوّض كائنات العناصر المنبثقة إلى الأهداف المُحدّدة إذا كان هناك مُحدِد مُمرّر. يُستخدَم هذا الخيّار عمليًّا لتفعيل محتوى HTML ديناميكيّ لإضافة عناصر منبثقة. انظر هنا وهذا المثال المفيد. |
template (قالب)
|
سلسلة محارف | '<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'
|
شفرة HTML قاعديّة للاستخدام أثناء إنشاء العنصُر المنبثق. يُحقَن عنوان العنصُر المنبثق ( يُحقَن مُحتوى العنصُر المنبثق ( تصبح قيمة يجب أن يحوي العنصُر المغلِّف الأعلى الصنف |
title (العنوان)
|
عنصُر | دالّة |
قيمة العنوان المبدئيّة إنْ لم تكن الخاصيّة عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر | |
trigger (التفعيل)
|
سلسلة محارف | 'click'
|
click (النقر) | hover (الحومان) | focus (تركيز المؤشّر) | manual (يدويًّا). يمكن تعيين أكثر من طريقة، افصل بينها بمسافة. لا يمكن الجمع بين التفعيل يدويًّا manual وأي طريقة أخرى.
|
offset (الانزياح)
|
سلسلة محارف | 0
|
انزيّاح العنصُر المنبثق عن العنصُر المستهدَف. راجع توثيق Offset في Popper.js. |
fallbackPlacement (موضع التراجع)
|
مصفوفة | 'flip'
|
يسمح بتحديد الموضع الذي سيختاره Popper.js عند التراجع Fallback. راجع توثيق Popper.js للمزيد من المعلومات. |
boundary (حدود)
|
عنصُر | 'scrollParent'
|
حدود قيد طفح Overflow العنصُر المنبثق. يقبل القيم 'viewport' (إطار العرض)، أو'window' (نافذة)، أو 'scrollParent' (عنصُر أب يقبل التمرير) أو عنصُر HTML (فقط عند استخدام JavaScript). راجع توثيق Popper.js للمزيد من المعلومات.
|
خاصيّات البيانات لعناصر منبثقة منفردة
يمكن تعيين خيّارات بديلة لعناصر منبثقة على انفراد باستخدام خاصيّات البيانات كما هو محدَّد أعلاه.
التوابع
تنبيه: التوابع غير المتزامنة والانتقالات
توابع واجهة التطبيقات جميعها غير متزامنة وتشغّل انتقالا. تعود هذه التوابع لشفرة الاستدعاء مباشرةً بعد بدء الانتقال، لكن قبل أن ينتهي. علاوةً على ذلك، يُتجاهل استدعاء تابع على مكوِّن في طور الانتقال.
$().popover(options)
يمهِّد العناصر المنبثقة المتعلّقة بمجموعة من العناصر.
.popover('show')
يُظهر العنصُر المنبثق المتعلِّق بعنصُر. يعود إلى المُستدعِي قبل أن يُعرَض العنصُر المنبثق فعليًّا (أي قبل وقوع الحدث shown.bs.popover). يُعدّ استخدام هذا التابع عرضًا يدويًّا للعنصُر المنبثق. لا تُعرَض العناصر المنبثقة ذات العنوان والمحتوى الفارغيْن (طول سلسلة المحارف يساوي صفرا).
$('#element').popover('show')
.popover('hide')
يخفي العنصُر المنبثق المتعلِّق بعنصُر. يعود إلى المُستدعِي قبل أن يُخفَى العنصُر المنبثق فعليًّا (أي قبل وقوع الحدث hidden.bs.popover). يُعدّ استخدام هذا التابع إخفاءً يدويًّا للعنصُر المنبثق.
$('#element').popover('hide')
.popover('toggle')
يبدّل حالة العنصُر المنبثق المتعلِّق بعنصُر (يُخفيه عندما ما يكون ظاهرًا، والعكس). يعود إلى المُستدعِي قبل أن يُظهَر العنصُر المنبثق أو يُخفَى فعليًّا (أي قبل وقوع الحدث hidden.bs.popover أو shown.bs.popover). يُعدّ استخدام هذا التابع إخفاءً يدويًّا للعنصُر المنبثق.
$('#element').popover('toggle')
.popover('dispose')
يخفي العنصُر المنبثق ويحذفه. لا يمكن حذف العناصر المنبثقة التي تستخدم التفويض (أي التي أُنشِئت باستخدام المُحدِّد selector) فرديًّا من العناصر الأبناء.
$('#element').popover('dispose')
.popover('enable')
يمنح العنصُر المنبثق المتعلِّق بعنصُر قابليّة العرض. تُفعَّل العناصر المنبثقة مبدئيّا.
$('#element').popover('enable')
.popover('disable')
يحذف قابليّة العرض من العنصُر المنبثق المتعلِّق بعنصُر. لن يمكن عرض العنصُر المنبثق بعدها إلّا إذا أعيد تفعيل قابليّة عرضه.
$('#element').popover('disable')
.popover('toggleEnabled')
يبدّل حالة قابليّة العرض الخاصّة بالعنصُر المنبثق المتعلِّق بعنصُر.
$('#element').popover('toggleEnabled')
.popover('update')
يحدّث موضع العنصُر المنبثق المتعلِّق بعنصُر
$('#element').popover('update')
الأحداث
| نوع الحدث | الوصف |
|---|---|
show.bs.popover
|
يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع show .
|
shown.bs.popover
|
يُطلَق هذا الحدث عندما يُصبح العنصر المنبثق مرئيًّا للزائر (ينتظر اكتمال انتقالات CSS). |
hide.bs.popover
|
يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع hide .
|
hidden.bs.popover
|
يُطلَق هذا الحدث عندما يكتمل إخفاء العنصر المنبثق عن الزائر (ينتظر اكتمال انتقالات CSS). |
inserted.bs.popover
|
يُطلَق هذا الحدث بعد الحدث show.bs.popover عندما يُضاف قالب العنصُر المنبثق إلى كائن المستند.
|
$('#myPopover').on('hidden.bs.popover', function () {
// افعل شيئا هنا …
})