پاپاورها
اسناد و نمونه هایی برای افزودن پاپاورهای بوت استرپ، مانند مواردی که در iOS یافت می شوند، به هر عنصری در سایت شما.
بررسی اجمالی
نکاتی که هنگام استفاده از افزونه popover باید بدانید:
- Popover ها برای موقعیت یابی به کتابخانه شخص ثالث Popper متکی هستند . شما باید popper.min.js را قبل از bootstrap.js اضافه کنید یا از
bootstrap.bundle.min.js
/bootstrap.bundle.js
که حاوی Popper است استفاده کنید تا پاپاورها کار کنند! - Popover ها به افزونه tooltip به عنوان یک وابستگی نیاز دارند.
- Popover ها به دلایل عملکردی انتخاب می شوند، بنابراین باید خودتان آنها را مقداردهی اولیه کنید .
- طول صفر
title
وcontent
مقادیر هرگز پاپاور را نشان نمی دهند. container: 'body'
برای جلوگیری از بروز مشکلات در مؤلفههای پیچیدهتر (مانند گروههای ورودی، گروههای دکمهها و غیره) آن را مشخص کنید .- راه اندازی پاپاور روی عناصر پنهان کار نخواهد کرد.
- پاپاور برای
.disabled
یاdisabled
عناصر باید روی یک عنصر لفافی فعال شوند. - هنگامی که از لنگرهایی که در چندین خط قرار می گیرند، پاپاورها بین عرض کلی لنگرها در مرکز قرار می گیرند. برای جلوگیری از این رفتار از
.text-nowrap
روی s خود استفاده کنید.<a>
- Popover ها باید قبل از حذف عناصر مربوطه از DOM پنهان شوند.
- پاپا��رها را می توان به لطف عنصری در داخل یک DOM سایه فعال کرد.
prefers-reduced-motion
اثر انیمیشن این مؤلفه به پرسش رسانه
بستگی دارد
. بخش
حرکت کاهش یافته اسناد دسترسی ما را ببینید.
به خواندن ادامه دهید تا ببینید پاپاورها با چند مثال چگونه کار می کنند.
مثال: پاپاورها را در همه جا فعال کنید
یک راه برای مقداردهی اولیه همه پاپاورها در یک صفحه این است که آنها را با ویژگی آنها انتخاب کنید data-bs-toggle
:
var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
return new bootstrap.Popover(popoverTriggerEl)
})
مثال: با استفاده از container
گزینه
وقتی چند سبک روی یک عنصر والد دارید که با پاپاور تداخل دارد، باید یک سفارشی را مشخص کنید container
تا به جای آن HTML پاپاور در آن عنصر ظاهر شود.
var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
container: 'body'
})
مثال
<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>
چهار جهت
چهار گزینه موجود است: تراز بالا، راست، پایین و چپ. هنگام استفاده از Bootstrap در RTL، دستورالعمل ها منعکس می شوند.
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
Popover on top
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
Popover on right
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
Popover on left
</button>
رد کردن با کلیک بعدی
از focus
ماشه برای رد کردن پاپاورها در کلیک بعدی کاربر بر روی عنصری متفاوت از عنصر تعویض استفاده کنید.
نشانهگذاری خاصی برای رد کردن روی کلیک بعدی لازم است
برای رفتار مناسب بین مرورگرها و کراس پلتفرم ها، باید از تگ استفاده کنید <a>
، نه<button>
تگ، و همچنین باید یک tabindex
ویژگی را وارد کنید.
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
trigger: 'focus'
})
عناصر غیر فعال
عناصر دارای disabled
ویژگی تعاملی نیستند، به این معنی که کاربران نمی توانند ماوس را نگه دارند یا روی آنها کلیک کنند تا پاپ اور (یا راهنمای ابزار) راه اندازی شود. بهعنوان راهحل، میخواهید پاپاور را از یک لفاف <div>
یا <span>
با استفاده از صفحه کلید که بهطور ایدهآل ساخته شده است، فعال tabindex="0"
کنید.
برای راهاندازهای پاپاور غیرفعال، ممکن است ترجیح data-bs-trigger="hover focus"
دهید که پاپاور بهعنوان بازخورد بصری فوری برای کاربران شما ظاهر شود زیرا ممکن است انتظار نداشته باشند روی یک عنصر غیرفعال کلیک کنند.
<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
<button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>
ساس
متغیرها
$popover-font-size: $font-size-sm;
$popover-bg: $white;
$popover-max-width: 276px;
$popover-border-width: $border-width;
$popover-border-color: rgba($black, .2);
$popover-border-radius: $border-radius-lg;
$popover-inner-border-radius: subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow: $box-shadow;
$popover-header-bg: shade-color($popover-bg, 6%);
$popover-header-color: $headings-color;
$popover-header-padding-y: .5rem;
$popover-header-padding-x: $spacer;
$popover-body-color: $body-color;
$popover-body-padding-y: $spacer;
$popover-body-padding-x: $spacer;
$popover-arrow-width: 1rem;
$popover-arrow-height: .5rem;
$popover-arrow-color: $popover-bg;
$popover-arrow-outer-color: fade-in($popover-border-color, .05);
استفاده
فعال کردن پاپاورها از طریق جاوا اسکریپت:
var exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)
ساخت پاپاورها برای کاربران صفحه کلید و فناوری کمکی
برای اینکه به کاربران صفحه کلید اجازه دهید پاپاورهای شما را فعال کنند، باید آنها را فقط به عناصر HTML اضافه کنید که به طور سنتی قابل تمرکز روی صفحه کلید و تعاملی هستند (مانند پیوندها یا کنترل های فرم). اگرچه عناصر HTML دلخواه (مانند <span>
s) را می توان با افزودن این tabindex="0"
ویژگی قابل تمرکز کرد، اما این کار باعث می شود تا تب های بالقوه آزاردهنده و گیج کننده بر روی عناصر غیر تعاملی برای کاربران صفحه کلید اضافه شود، و اکثر فناوری های کمکی در حال حاضر محتوای popover را در این شرایط اعلام نمی کنند. . علاوه بر این، صرفاً به hover
عنوان محرک پاپاورهای خود متکی نباشید، زیرا این کار باعث میشود که آنها را برای کاربران صفحه کلید غیرممکن کند.
در حالی که میتوانید با این گزینه HTML غنی و ساختار یافته را در پاپاورها وارد html
کنید، ما قویاً توصیه میکنیم که از افزودن بیش از حد محتوا خودداری کنید. روشی که پاپاورها در حال حاضر کار می کنند این است که پس از نمایش، محتوای آنها به عنصر ماشه با aria-describedby
ویژگی گره خورده است. در نتیجه، کل محتوای پاپاور به عنوان یک جریان طولانی و بدون وقفه به کاربران فناوری کمکی اعلام خواهد شد.
علاوه بر این، در حالی که میتوانید کنترلهای تعاملی (مانند عناصر فرم یا پیوندها) را نیز در پاپاور خود بگنجانید (با افزودن این عناصر به allowList
ویژگیها و برچسبهای مجاز)، توجه داشته باشید که در حال حاضر popover ترتیب فوکوس صفحهکلید را مدیریت نمیکند. هنگامی که کاربر صفحه کلید یک پاپاور را باز می کند، تمرکز روی عنصر آغازگر باقی می ماند، و از آنجایی که پاپاور معمولاً بلافاصله از ماشه در ساختار سند پیروی نمی کند، هیچ تضمینی برای حرکت به جلو/فشار دادن وجود ندارد.TABکاربر صفحه کلید را به خود پاپاور منتقل می کند. به طور خلاصه، افزودن ساده کنترلهای تعاملی به یک پاپاور احتمالاً این کنترلها را برای کاربران صفحهکلید و کاربران فناوریهای کمکی غیرقابل دسترس/غیرقابل استفاده میکند، یا حداقل یک ترتیب تمرکز کلی غیرمنطقی را ایجاد میکند. در این موارد، به جای آن از یک گفتگوی مودال استفاده کنید.
گزینه ها
گزینه ها را می توان از طریق ویژگی های داده یا جاوا اسکریپت منتقل کرد. data-bs-
برای ویژگی های داده، نام گزینه را به مانند در ضمیمه کنید data-bs-animation=""
. هنگام عبور گزینه ها از طریق ویژگی های داده، حتماً نوع حروف نام گزینه را از camelCase به kebab-case تغییر دهید. به عنوان مثال، به جای استفاده از data-bs-customClass="beautifier"
، استفاده کنید data-bs-custom-class="beautifier"
.
sanitize
,
sanitizeFn
و
allowList
نمی توانند با استفاده از ویژگی های داده ارائه شوند.
نام | تایپ کنید | پیش فرض | شرح |
---|---|---|---|
animation |
بولی | true |
یک انتقال محو شدن CSS به پاپاور اعمال کنید |
container |
رشته | عنصر | نادرست | false |
popover را به یک عنصر خاص اضافه می کند. مثال: |
content |
رشته | عنصر | عملکرد | '' |
اگر تابعی داده شود، با |
delay |
شماره | هدف - شی | 0 |
تاخیر در نمایش و پنهان کردن پاپاور (ms) - برای نوع ماشه دستی اعمال نمی شود اگر شماره ای ارائه شود، تاخیر برای هر دو پنهان/نمایش اعمال می شود ساختار شیء عبارت است از: |
html |
بولی | false |
HTML را در پاپاور قرار دهید. اگر نادرست باشد، innerText از ویژگی برای درج محتوا در DOM استفاده می شود. اگر نگران حملات XSS هستید از متن استفاده کنید. |
placement |
رشته | عملکرد | 'right' |
نحوه قرار دادن پاپاور - خودکار | بالا | پایین | چپ | درست. هنگامی که یک تابع برای تعیین مکان استفاده می شود، با گره popover DOM به عنوان اولین آرگومان و عنصر آغازگر DOM به عنوان دومین آرگومان فراخوانی می شود. متن |
selector |
رشته | نادرست | false |
اگر انتخابگر ارائه شود، اشیاء پاپاور به اهداف مشخص شده واگذار می شود. در عمل، از این برای فعال کردن محتوای پویا HTML برای افزودن پاپاور استفاده میشود. این و یک مثال آموزنده را ببینید . |
template |
رشته | '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>' |
پایه HTML برای استفاده در هنگام ایجاد پاپاور. پاپاور به پاپاور به
خارجی ترین عنصر پوشش باید دارای |
title |
رشته | عنصر | عملکرد | '' |
اگر تابعی داده شود، با |
trigger |
رشته | 'click' |
چگونه پاپاور راه اندازی می شود - کلیک کنید | شناور | تمرکز | کتابچه راهنمای. شما ممکن است چندین محرک عبور دهید. آنها را با فاصله جدا کنید. manual نمی توان با هیچ محرک دیگری ترکیب کرد. |
fallbackPlacements |
آرایه | ['top', 'right', 'bottom', 'left'] |
با ارائه لیستی از قرارگیری ها در آرایه (به ترتیب اولویت) مکان های جایگزین را تعریف کنید. برای اطلاعات بیشتر به اسناد رفتاری پوپر مراجعه کنید |
boundary |
رشته | عنصر | 'clippingParents' |
مرز محدودیت سرریز پاپاور (فقط برای اصلاح کننده preventOverflow Popper اعمال می شود). به طور پیشفرض 'clippingParents' میتواند یک مرجع HTMLElement را بپذیرد (فقط از طریق جاوا اسکریپت). برای اطلاعات بیشتر به Popper's detectOverflow docs مراجعه کنید. |
customClass |
رشته | عملکرد | '' |
وقتی پاپاور نشان داده شد، کلاسها را به آن اضافه کنید. توجه داشته باشید که این کلاس ها علاوه بر کلاس های مشخص شده در قالب اضافه خواهند شد. برای اضافه کردن چند کلاس، آنها را با فاصله از هم جدا کنید همچنین میتوانید تابعی را ارسال کنید که باید یک رشته حاوی نامهای کلاس اضافی را برگرداند. |
sanitize |
بولی | true |
پاکسازی را فعال یا غیرفعال کنید. در صورت فعال شدن 'template' ، گزینه 'content' ها 'title' ضد عفونی خواهند شد. بخش ضدعفونی کننده را در مستندات جاوا اسکریپت ما ببینید. |
allowList |
هدف - شی | مقدار پیش فرض | شیئی که حاوی ویژگی ها و برچسب های مجاز است |
sanitizeFn |
null | عملکرد | null |
در اینجا می توانید عملکرد ضدعفونی کننده خود را ارائه دهید. اگر ترجیح می دهید از یک کتابخانه اختصاصی برای انجام پاکسازی استفاده کنید، می تواند مفید باشد. |
offset |
آرایه | رشته | عملکرد | [0, 8] |
جبران پوپاور نسبت به هدفش. شما می توانید یک رشته را در ویژگی های داده با مقادیر جدا شده با ویرگول مانند: هنگامی که یک تابع برای تعیین offset استفاده می شود، با یک شی حاوی popper placement، مرجع، و popper rects به عنوان اولین آرگومان فراخوانی می شود. گره DOM عنصر محرک به عنوان آرگومان دوم ارسال می شود. تابع باید یک آرایه با دو عدد برگرداند: . برای اطلاعات بیشتر به اسناد افست پوپر مراجعه کنید . |
popperConfig |
null | شی | عملکرد | null |
برای تغییر تنظیمات Popper پیشفرض Bootstrap، به پیکربندی Popper مراجعه کنید . هنگامی که یک تابع برای ایجاد پیکربندی Popper استفاده می شود، با یک شی که حاوی تنظیمات پیش فرض Popper Bootstrap است فراخوانی می شود. این به شما کمک می کند تا از تنظیمات پیش فرض استفاده کرده و با پیکربندی خود ادغام کنید. تابع باید یک شی پیکربندی برای Popper برگرداند. |
ویژگی های داده برای پاپاورهای فردی
همانطور که در بالا توضیح داده شد، میتوان گزینههای مربوط به پاپاورهای فردی را از طریق استفاده از ویژگیهای داده مشخص کرد.
استفاده از تابع باpopperConfig
var popover = new bootstrap.Popover(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
مواد و روش ها
روش ها و انتقال های ناهمزمان
همه متدهای API ناهمزمان هستند و یک انتقال را شروع می کنند . آنها به محض شروع انتقال اما قبل از پایان آن به تماس گیرنده باز می گردند . علاوه بر این، فراخوانی متد بر روی یک جزء انتقال نادیده گرفته خواهد شد .
نشان می دهد
پاپاور یک عنصر را آشکار می کند. قبل از اینکه پاپاور واقعاً نشان داده شود (یعنی قبل از shown.bs.popover
وقوع رویداد) به تماس گیرنده برمی گردد. این به عنوان یک راهاندازی «دستی» پاپاور در نظر گرفته میشود. پاپاورهایی که عنوان و محتوای آنها هر دو با طول صفر است هرگز نمایش داده نمی شوند.
myPopover.show()
پنهان شدن
پاپاور یک عنصر را پنهان می کند. قبل از اینکه پاپاور واقعاً پنهان شود (یعنی قبل از hidden.bs.popover
وقوع رویداد) به تماس گیرنده برمی گردد. این به عنوان یک راهاندازی «دستی» پاپاور در نظر گرفته میشود.
myPopover.hide()
تغییر وضعیت
popover یک عنصر را تغییر می دهد. قبل از اینکه پاپاور واقعاً نشان داده یا پنهان شود (یعنی قبل از وقوع رویداد shown.bs.popover
یا hidden.bs.popover
رویداد) به تماس گیرنده برمی گردد. این به عنوان یک راهاندازی «دستی» پاپاور در نظر گرفته میشود.
myPopover.toggle()
در معرض قرار دادن
پاپاور یک عنصر را پنهان و از بین می برد (داده های ذخیره شده در عنصر DOM را حذف می کند). پاپاورهایی که از تفویض استفاده میکنند (که با استفاده از selector
گزینه ایجاد میشوند ) را نمیتوان بهصورت جداگانه در عناصر ماشهای نزول از بین برد.
myPopover.dispose()
فعال کردن
به پاپاور یک عنصر قابلیت نشان دادن می دهد. Popover ها به طور پیش فرض فعال هستند.
myPopover.enable()
غیر فعال کردن
قابلیت نمایش پاپاور یک عنصر را حذف می کند. Popover فقط در صورت فعال شدن مجدد قابل نمایش است.
myPopover.disable()
toggleEnabled
قابلیت نمایش یا پنهان کردن پاپاور یک عنصر را تغییر میدهد.
myPopover.toggleEnabled()
به روز رسانی
موقعیت popover یک عنصر را به روز می کند.
myPopover.update()
getInstance
روش ایستا که به شما امکان می دهد نمونه popover مرتبط با یک عنصر DOM را دریافت کنید
var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance
getOrCreateInstance
روش ایستا که به شما امکان می دهد نمونه popover مرتبط با یک عنصر DOM را دریافت کنید یا در صورتی که اولیه نشده بود، یک نمونه جدید ایجاد کنید.
var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap popover instance
مناسبت ها
نوع رویداد | شرح |
---|---|
show.bs.popover | این رویداد بلافاصله پس از show فراخوانی متد نمونه فعال می شود. |
نشان داده شده.ب.اس.پاپور | این رویداد زمانی فعال می شود که پاپاور برای کاربر قابل مشاهده باشد (منتظر تکمیل انتقال CSS می شود). |
hide.bs.popover | این رویداد بلافاصله پس از hide فراخوانی متد نمونه فعال می شود. |
hidden.bs.popover | این رویداد زمانی فعال می شود که پاپ اور از کاربر مخفی شود (منتظر تکمیل انتقال CSS می شود). |
درج شده.bs.popover | این رویداد پس از show.bs.popover رویداد زمانی که قالب popover به DOM اضافه شده است فعال می شود. |
var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
// do something...
})