الفرق بين المراجعتين لصفحة: «Bootstrap/popovers»

من موسوعة حسوب
→ التعديل السابق
مرئينص الويكي
لا ملخص تعديل
لا ملخص تعديل
 
(5 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة)
سطر 3: سطر 3:
== نظرة عامّة ==
== نظرة عامّة ==
في ما يلي أمور ينبغي إدراكها قبل البدء في استخدام مكوِّن العناصر المنبثقة الذي يوفّره Bootstrap:
في ما يلي أمور ينبغي إدراكها قبل البدء في استخدام مكوِّن العناصر المنبثقة الذي يوفّره Bootstrap:
* تعتمد العناصر المنبثقة على مكتبة [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.
* تعتمد العناصر المنبثقة على مكتبة [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>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>&lt;a&gt;</code> لتفادي هذا الأمر.
* تتوسّط العناصر المنبثقة عند ابتدائها من روابط تلتفّ على أسطر متعدّدة تتوسّط العرض الكامل للرابط. استخدم الخاصيّة <code>[[CSS/white-space|white-space]]: nowrap;‎</code> على الرابط <code>[[HTML/a|&lt;a&gt;]]</code> لتفادي هذا الأمر.
* يجب إخفاء العناصر المنبثقة حتى يتسنّى حذفُ العناصر المتعلّقة بها من كائن المستند DOM.
* يجب إخفاء العناصر المنبثقة حتى يتسنّى حذفُ العناصر المتعلّقة بها من كائن المستند DOM.
* يمكن ابتداء من عنصر داخل ظل شجرة DOM.
'''ملحوظة''': تأثير الحركة الخاص بهذه المكونة يعتمد على استعلام الوسائط <code>prefers-reduced-motion</code>. راجع [[Bootstrap/accessibility|صفحة سهولة الوصول]] لمزيد من المعلومات.


واصل القراءة لأمثلة عن كيفيّة عمل العناصر المنبثقة.
واصل القراءة لأمثلة عن كيفيّة عمل العناصر المنبثقة.
== مثال: تفعيل العناصر المنبثقة في كلّ مكان ==
== مثال: تفعيل العناصر المنبثقة في كل مكان ==
إحدى طرق تمهيد Initialization جميع العناصر المنبثقة في صفحة هي تحديدها باستخدام قيمة <code>data-toggle</code> الخاصّة بها (<code>data-toggle="popover"‎</code>).
إحدى طرائق تمهيد (initialization) جميع العناصر المنبثقة في صفحة هي تحديدها باستخدام قيمة <code>data-toggle</code> الخاصّة بها (<code>data-toggle="popover"‎</code>).
<syntaxhighlight lang="javascript">
<syntaxhighlight lang="javascript">
$(function () {
$(function () {
سطر 22: سطر 24:
})
})
</syntaxhighlight>
</syntaxhighlight>
== مثال: استخدام الخيّار <code>container</code> ==
== مثال: استخدام الخيار <code>container</code> ==
عندما تكون هناك أنماط على عنصُر أب تتداخل مع عنصُر منبثق فستحتاج لتحديد حاويّة (<code>container</code>) مُخصَّصة بحيث تظهر شفرة HTML الخاصّة بالعنصُر المنبثق داخل الحاويّة.
عندما تكون هناك أنماط على عنصُر أب تتداخل مع عنصُر منبثق فستحتاج لتحديد حاويّة (<code>container</code>) مُخصَّصة بحيث تظهر شفرة HTML الخاصّة بالعنصُر المنبثق داخل الحاويّة.
<syntaxhighlight lang="javascript">
<syntaxhighlight lang="javascript">
سطر 35: سطر 37:
<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: سطر 56:
</button>
</button>
</syntaxhighlight>
</syntaxhighlight>
=== الإخفاء عند النقر خارج العنصُر ===
=== الإخفاء عند النقر خارج العنصر ===
استخدم الخاصيّة <code>focus</code> لإخفاء العنصُر المنبثق عند نقر المستخدم على عنصُر مغاير للذي تسبّب في إظهار العنصُر المنبثق.
استخدم الخاصيّة <code>focus</code> لإخفاء العنصُر المنبثق عند نقر المستخدم على عنصُر مغاير للذي تسبّب في إظهار العنصُر المنبثق.
'''تنبيه:''' تتطلّب هذه الميزة لكي تعمل على مختلف المنصّات والمتصفّحات استخدام الوسم <code><a></code> _لا_ الوسم <code><button></code>، كما يجب أن تضمِّن الخاصيّة [https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex <code>tabindex</code>].
 
'''تنبيه:''' تتطلّب هذه الميزة لكي تعمل على مختلف المنصّات والمتصفّحات استخدام الوسم <code></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: سطر 68:
})
})
</syntaxhighlight>
</syntaxhighlight>
=== العناصر المُعطَّلة ===
=== العناصر المعطلة ===
لا تعدّ العناصر التي تُطبَّق عليها الخاصيّة <code>disabled</code> تفاعليّة، ممّا يعني أنّ المستخدمين لا يستطيعون الحومان فوقها أو النقر عليها لإظهار عنصُر منبثق (أو تلميح). الحلّ البديل هو إظهار عنصُر منبثق من عنصُر مغلِّف (<code>&lt;div&gt;</code> أو <code>&lt;span&gt;</code>) وإبطال أحداث المؤشِّر (<code>pointer-events</code>) على العنصُر المُعطَّل.
لا تعدّ العناصر التي تُطبَّق عليها الخاصيّة <code>disabled</code> تفاعليّة، ممّا يعني أنّ المستخدمين لا يستطيعون الحومان فوقها أو النقر عليها لإظهار عنصُر منبثق (أو تلميح). الحلّ البديل هو إظهار عنصُر منبثق من عنصُر مغلِّف (<code>[[HTML/div|&lt;div&gt;]]</code> أو <code>[[HTML/span|&lt;span&gt;]]</code>) وإبطال أحداث المؤشِّر (<code>pointer-events</code>) على العنصُر المُعطَّل.
 
يمكن كذلك استخدام الخاصيّة <code>data-trigger="hover"‎</code> لابتداء العنصُر المنبثق مباشرةً إذْ قد لا يتوقّع الزائر أنّ بإمكانه ''النقر'' على عنصُر مُعطَّل.
يمكن كذلك استخدام الخاصيّة <code>data-trigger="hover"‎</code> لابتداء العنصُر المنبثق مباشرةً إذْ قد لا يتوقّع الزائر أنّ بإمكانه ''النقر'' على عنصُر مُعطَّل.
<syntaxhighlight lang="html">
<syntaxhighlight lang="html">
سطر 74: سطر 78:
</syntaxhighlight>
</syntaxhighlight>


== استخدام مُلحَق JavaScript ==
== استخدام ملحق 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>) عند التمرير عبر خاصيّات البيانات.
=== جعل العناصر المنبثقة تعمل مع لوحة المفاتيح والتقنيات المساعدة ===
{|class="wikitable"
إن أردت السماح لمستخدمي لوحة المفاتيح بتنشيط العناصر المنبثقة، فلا ينبغي أن تضيفها إلّا إلى عناصر HTML التي تتفاعل مع لوحة المفاتيح (مثل الروابط أو عناصر النموذج). ورغم أنّه يمكن جعل عناصر HTML الأخرى (مثل <code><nowiki><span></nowiki></code>) قابلة لاستقبال التركيز عن طريق إضافة السمة <code>tabindex = "0"</code>‎ ، إلا أنّ ذلك سيضيف مواضع توقف مربكة على العناصر غير التفاعلية. معظم التقنيات المساعدة حاليًا لا تعلن المحتوى المنبثق في هذه الحالة. علاوة على ذلك، لا ينبغي أن تعتمد حصرَا على الحومان لجعل العنصر ينبثق، ذلك أنّ هذا سيمنع مستخدمي لوحة المفاتيح من إطلاقها.
 
رغم أنه يمكنك إدراج ترميز لغة HTML في العناصر المنبثقة باستخدام خيار <code>html</code>، فإننا نوصي بشدة بتجنب إضافة الكثير من المحتوى. بمجرد عرض العنصر المنبثق popovers، يرتبط محتواه بعنصر الإطلاق في السمة <code>aria-describedby</code>. ونتيجةً لذلك سيُعرَض كل محتوى العنصر المنبثق لمستخدمي التكنولوجيا المساعدة عرضًا واحدا طويلا غير متقطع.
 
في حين أنه يجوز أيضًا تضمين عناصر تحكم تفاعلية (مثل عناصر النموذج أو الروابط) في العنصر المنبثق (عن طريق إضافة هذه العناصر إلى القائمة البيضاء أو السمات والوسوم المسموح بها) ، تذكر أنّ العناصر المنبثقة حاليًا لا تنظم ترتيب تركيز لوحة المفاتيح. عندما يفتح مستخدم لوحة المفاتيح عنصرا منبثقًا ، يظل التركيز على العنصر الذي أطلق العنصر المنبثق، وبما أنّ العناصر المنبثقة لا تتبع عادةً عنصر الإطلاق في بنية المستند ، فلا يوجد ضمان بأنّ الانتقال إلى الأمام أو النقر على <code>TAB</code> سينقل مستخدم لوحة المفاتيح إلى العنصر المنبثق نفسه. باختصار ، إنّ إضافة عناصر تحكم تفاعلية إلى العنصر المنبثق سيجعلها على الأرجح غير قابلة للاستخدام / الوصول لمستخدمي لوحة المفاتيح ومستخدمي التقنيات المساعدة، أو على الأقل سيجعل ترتيب التركيز غير منطقي عمومًا. قد يكون الأفضل في هذه الحالات استخدام مربع حوار شرطي.
 
=== الخيارات ===
يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق [[JavaScript]]. ألحق اسم الخيّار بالكلمة <code>data-‎</code> (مثلًا <code>data-animation=""‎</code> للخيّار <code>animation</code>) عند التمرير عبر خاصيّات البيانات.
{| class="wikitable"
!الاسم
!الاسم
!النوع
!النوع
سطر 87: سطر 99:
!الوصف
!الوصف
|-
|-
|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>''</code>
|سلسلة نصية فارغة
|
|
تأخذ القيمة المبدئيّة إن لم تكن الخاصيّة <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>
|
|
تموضع العنصُر المنبثق: - auto (تلقائي) | top (أعلى) | bottom (أسفل) | left (يسار) | right (يمين).<br>يُعاد توجيه العنصُر المنبثق تلقائيَّا عند اختيّار التموضع التلقائي (<code>auto</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> (قالب)
|سلسلة محارف
|سلسلة محارف
|'‎&lt;div class="popover" role="tooltip"&gt;&lt;div class="arrow"&gt;&lt;/div&gt;&lt;h3 class="popover-header"&gt;&lt;/h3&gt;&lt;div class="popover-body"&gt;&lt;/div&gt;&lt;/div&gt;‎'
|<code>'‎&lt;div class="popover" role="tooltip"&gt;&lt;div class="arrow"&gt;&lt;/div&gt;&lt;h3 class="popover-header"&gt;&lt;/h3&gt;&lt;div class="popover-body"&gt;&lt;/div&gt;&lt;/div&gt;‎'</code>
|
|
شفرة HTML قاعديّة للاستخدام أثناء إنشاء العنصُر المنبثق
شفرة HTML قاعديّة للاستخدام أثناء إنشاء العنصُر المنبثق.
يُحقَن عنوان العنصُر المنبثق (<code>title</code>) في الصنف (<code>.popover-header</code>).
 
يُحقَ مُحتوى العنصُر المنبثق (<code>content</code>) في الصنف <code>.popover-body</code>.
يُحقَن عنوان العنصُر المنبثق (<code>title</code>) في الصنف (<code>‎.popover-header</code>).
تصبح قيمة <code>.arrow</code> قيمة الخاصيّة <code>arrow</code> في العنصُر المنبثق.
 
يجب أن يحوي العنصُر المغلِّف الأعلى الصنف <code>.popover</code> .
يُحقَن مُحتوى العنصُر المنبثق (<code>content</code>) في الصنف ‎<code>.popover-body</code>.
 
تصبح قيمة ‎<code>.arrow</code> قيمة الخاصيّة <code>arrow</code> في العنصُر المنبثق.
 
يجب أن يحوي العنصُر المغلِّف الأعلى الصنف ‎<code>.popover</code> .
|-
|-
|title (العنوان)
|<code>title</code> (العنوان)
|سلسلة محارف | عنصُر | دالّة
| سلسلة محارف |<nowiki> عنصُر | دالّة</nowiki>
|<code>''</code>
|
|
|
قيمة العنوان المبدئيّة إنْ لم تكن الخاصيّة <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].
<a href=""></a>.
|-
|-
|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] للمزيد من المعلومات.
|-
|<code>sanitize</code>
|قيمة منطقية
|<code>true</code>
|يتيح أو يعطل التصحيح. في حال تفعيلها، ستُصحّح كلّ من <code>'template'</code>و <code>'content'</code> و <code>'title'</code> 
|-
|<code>whiteList</code>
|كائن
|[[Bootstrap/javascript#.D8.A7.D9.84.D9.85.D8.B5.D8.AD.D8.AD.D8.A7.D8.AA Sanitizers|القيمة الافتراضية]]
|كائن يحتوي السمات والوسوم المسموح بها
|-
|<code>sanitizeFn</code>
|قيمة معدومة أو دالة
|قيمة معدومة
|يمكنك هنا تخصيص دالة التصحيح. هذا مفيد في حال كنت تفضل استخدام مكتبة خاصة لإجراء التصحيح
|-
|<code>popperConfig</code>
|قيمة معدومة أو كائن
|قيمة معدومة
|لتغيير إعدادات Popper.js الافتراضية. راجع [https://popper.js.org/docs/v1/#Popper.Defaults هذه الصفحة] لمزيد من التفاصيل
|}
|}
==== خاصيّات البيانات لعناصر منبثقة منفردة ====
==== خاصيّات البيانات لعناصر منبثقة منفردة ====
سطر 174: سطر 215:
=== التوابع ===
=== التوابع ===
'''تنبيه: التوابع غير المتزامنة والانتقالات'''
'''تنبيه: التوابع غير المتزامنة والانتقالات'''
توابع واجهة التطبيقات جميعها غير متزامنة وتشغّل انتقالا. تعود هذه التوابع لشفرة الاستدعاء مباشرةً بعد بدء الانتقال، لكن قبل أن ينتهي. علاوةً على ذلك، يُتجاهل استدعاء تابع على مكوِّن في طور الانتقال.
توابع واجهة التطبيقات جميعها غير متزامنة وتشغّل انتقالا. تعود هذه التوابع لشفرة الاستدعاء مباشرةً بعد بدء الانتقال، لكن قبل أن ينتهي. علاوةً على ذلك، يُتجاهل استدعاء تابع على مكوِّن في طور الانتقال.
==== <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">
سطر 218: سطر 260:
</syntaxhighlight>
</syntaxhighlight>
=== الأحداث ===
=== الأحداث ===
{|class="wikitable"
{| class="wikitable"
!نوع الحدث
!نوع الحدث
!الوصف
!الوصف
|-
|-
|<code>show.bs.popover</code></td>
|<code>show.bs.popover</code>
|يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع <code>show</code> .</td>
|يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع <code>show</code> .
|-
|-
|<code>shown.bs.popover</code></td>
|<code>shown.bs.popover</code>
|يُطلَق هذا الحدث عندما يُصبح العنصر المنبثق مرئيًّا للزائر  (ينتظر اكتمال انتقالات CSS).</td>
|يُطلَق هذا الحدث عندما يُصبح العنصر المنبثق مرئيًّا للزائر  (ينتظر اكتمال انتقالات CSS).
|-
|-
|<code>hide.bs.popover</code></td>
|<code>hide.bs.popover</code>
|يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع <code>hide</code> .</td>
|يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع <code>hide</code> .
|-
|-
|<code>hidden.bs.popover</code></td>
|<code>hidden.bs.popover</code>
|يُطلَق هذا الحدث عندما يكتمل إخفاء العنصر المنبثق عن الزائر ((ينتظر اكتمال انتقالات CSS).
|يُطلَق هذا الحدث عندما يكتمل إخفاء العنصر المنبثق عن الزائر (ينتظر اكتمال انتقالات CSS).
|-
|-
|<code>inserted.bs.popover</code></td>
|<code>inserted.bs.popover</code>
|يُطلَق هذا الحدث بعد الحدث <code>show.bs.popover</code> عندما يُضاف قالب العنصُر المنبثق إلى كائن المستند.
|يُطلَق هذا الحدث بعد الحدث <code>show.bs.popover</code> عندما يُضاف قالب العنصُر المنبثق إلى كائن المستند.
|}
|}
سطر 244: سطر 286:
})
})
</syntaxhighlight>
</syntaxhighlight>
[[تصنيف:Bootstrap]][[تصنيف:Bootstrap components]]
 
== مصادر ==
* [https://getbootstrap.com/docs/4.5/components/popovers/ صفحة Popovers في توثيق Bootstrap].
[[تصنيف:Bootstrap|{{SUBPAGENAME}}]]
[[تصنيف:Bootstrap components|{{SUBPAGENAME}}]]

المراجعة الحالية بتاريخ 07:34، 13 يوليو 2020

استخدم العناصر المنبثقّة 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.
  • يمكن ابتداء من عنصر داخل ظل شجرة DOM.

ملحوظة: تأثير الحركة الخاص بهذه المكونة يعتمد على استعلام الوسائط prefers-reduced-motion. راجع صفحة سهولة الوصول لمزيد من المعلومات.

واصل القراءة لأمثلة عن كيفيّة عمل العناصر المنبثقة.

مثال: تفعيل العناصر المنبثقة في كل مكان

إحدى طرائق تمهيد (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 لإخفاء العنصُر المنبثق عند نقر المستخدم على عنصُر مغاير للذي تسبّب في إظهار العنصُر المنبثق.

تنبيه: تتطلّب هذه الميزة لكي تعمل على مختلف المنصّات والمتصفّحات استخدام الوسم وليس العنصر <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)

جعل العناصر المنبثقة تعمل مع لوحة المفاتيح والتقنيات المساعدة

إن أردت السماح لمستخدمي لوحة المفاتيح بتنشيط العناصر المنبثقة، فلا ينبغي أن تضيفها إلّا إلى عناصر HTML التي تتفاعل مع لوحة المفاتيح (مثل الروابط أو عناصر النموذج). ورغم أنّه يمكن جعل عناصر HTML الأخرى (مثل <span>) قابلة لاستقبال التركيز عن طريق إضافة السمة tabindex = "0"‎ ، إلا أنّ ذلك سيضيف مواضع توقف مربكة على العناصر غير التفاعلية. معظم التقنيات المساعدة حاليًا لا تعلن المحتوى المنبثق في هذه الحالة. علاوة على ذلك، لا ينبغي أن تعتمد حصرَا على الحومان لجعل العنصر ينبثق، ذلك أنّ هذا سيمنع مستخدمي لوحة المفاتيح من إطلاقها.

رغم أنه يمكنك إدراج ترميز لغة HTML في العناصر المنبثقة باستخدام خيار html، فإننا نوصي بشدة بتجنب إضافة الكثير من المحتوى. بمجرد عرض العنصر المنبثق popovers، يرتبط محتواه بعنصر الإطلاق في السمة aria-describedby. ونتيجةً لذلك سيُعرَض كل محتوى العنصر المنبثق لمستخدمي التكنولوجيا المساعدة عرضًا واحدا طويلا غير متقطع.

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

الخيارات

يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة data-‎ (مثلًا data-animation=""‎ للخيّار animation) عند التمرير عبر خاصيّات البيانات.

الاسم النوع القيمة المبدئيّة الوصف
animation (التحريك) قيمة منطقيّة true تطبيق تأثير الخفوت في CSS على العنصُر المنبثق
container (الحاويّة) عنصُر | false false

إلحاق العنصُر المنبثق بالعنصُر المخصوص. مثال: container: 'body'‎. هذا الخيّار مفيد جدًّا، إذ يمكّنك من وضع العنصُر المنبثق قرب العنصُر الذي يتعلّق به، ممّا يمنع العنصُر المنبثق من الابتعاد أثناء تغيير قياس النافذة.

content (المحتوى) عنصُر | دالّة سلسلة نصية فارغة

تأخذ القيمة المبدئيّة إن لم تكن الخاصيّة data-content موجودة على العنصُر المنبثق.

عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر this.

delay (تأخير) كائن 0

تأخير إظهار أو إخفاء العنصُر المنبثق (بالميلّي ثانيّة). لا ينطبق على العناصر المنبثقة المُظهرة يدويّا.

عند تمرير عدد فإنّ التأخير يُطبَّق على الإظهار (show) والإخفاء (hide) كليهما.

بنية الكائن هي كالتالي:

delay: { "show": 500, "hide": 100 }

html قيمة منطقيّة false إدراج وسوم HTML ضمن العنصُر المنبثق. تُستخدَم الدالّة text في jQuery لإدراج المحتوى في كائن المستند إذا كانت قيمة الخيّار false. استخدم نصّا إنْ كنت نصا بسيطًا إنْ كنت تخشى من هجمات XSS.
placement (التموضع) دالّة 'right'

تموضع العنصُر المنبثق: auto (تلقائي) | top (أعلى) | bottom (أسفل) | left (يسار) | right (يمين).
يُعاد توجيه العنصُر المنبثق تلقائيَّا عند اختيّار التموضع التلقائي (auto).

عند استخدام دالّة لتحديد التموضع فإنّ المُعطَى الأوّل الذي يُمرّر لها أثناء استدعائها هو مكان العنصُر المنبثق في كائن المستنَد والمُعطَى الثاني هو مكان العنصُر الذي تسبّب في إظهار العنصُر المنبثق. يُعيَّن سياق المتغيّر this إلى العنصُر المنبثق.

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) في الصنف (‎.popover-header).

يُحقَن مُحتوى العنصُر المنبثق (content) في الصنف ‎.popover-body.

تصبح قيمة ‎.arrow قيمة الخاصيّة arrow في العنصُر المنبثق.

يجب أن يحوي العنصُر المغلِّف الأعلى الصنف ‎.popover .

title (العنوان) عنصُر | دالّة

قيمة العنوان المبدئيّة إنْ لم تكن الخاصيّة title موجودة في العنصُر المنبثق

عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر this.

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 للمزيد من المعلومات.
sanitize قيمة منطقية true يتيح أو يعطل التصحيح. في حال تفعيلها، ستُصحّح كلّ من 'template'و 'content' و 'title' 
whiteList كائن القيمة الافتراضية كائن يحتوي السمات والوسوم المسموح بها
sanitizeFn قيمة معدومة أو دالة قيمة معدومة يمكنك هنا تخصيص دالة التصحيح. هذا مفيد في حال كنت تفضل استخدام مكتبة خاصة لإجراء التصحيح
popperConfig قيمة معدومة أو كائن قيمة معدومة لتغيير إعدادات 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 () {
  // افعل شيئا هنا …
})

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Bootstrap/popovers&oldid=29692»