Source

เคล็ดลับเครื่องมือ

เอกสารประกอบและตัวอย่างสำหรับการเพิ่มคำแนะนำเครื่องมือ Bootstrap แบบกำหนดเองด้วย CSS และ JavaScript โดยใช้ CSS3 สำหรับแอนิเมชั่นและแอตทริบิวต์ข้อมูลสำหรับการจัดเก็บชื่อในเครื่อง

ภาพรวม

สิ่งที่ควรทราบเมื่อใช้ปลั๊กอินคำแนะนำเครื่องมือ:

  • เคล็ดลับเครื่องมืออาศัยPopper.js ไลบรารีของบุคคลที่สาม สำหรับการวางตำแหน่ง คุณต้องรวมpopper.min.jsก่อน bootstrap.js หรือใช้bootstrap.bundle.min.js/ bootstrap.bundle.jsซึ่งมี Popper.js เพื่อให้คำแนะนำเครื่องมือทำงาน!
  • หากคุณกำลังสร้าง JavaScript จากแหล่งที่มา มันต้องการutil.js .
  • คำแนะนำเครื่องมือเป็นทางเลือกสำหรับเหตุผลด้านประสิทธิภาพ ดังนั้นคุณต้องเริ่มต้นด้วยตนเอง
  • คำแนะนำเครื่องมือที่มีชื่อความยาวเป็นศูนย์จะไม่แสดงขึ้น
  • ระบุcontainer: 'body'เพื่อหลีกเลี่ยงปัญหาการแสดงผลในองค์ประกอบที่ซับซ้อนมากขึ้น (เช่น กลุ่มอินพุต กลุ่มปุ่ม ฯลฯ)
  • คำแนะนำเครื่องมือทริกเกอร์ในองค์ประกอบที่ซ่อนอยู่จะไม่ทำงาน
  • คำแนะนำเครื่องมือสำหรับ.disabledหรือdisabledองค์ประกอบต้องถูกทริกเกอร์บนองค์ประกอบ wrapper
  • เมื่อถูกเรียกจากไฮเปอร์ลิงก์ที่มีหลายบรรทัด คำแนะนำเครื่องมือจะอยู่กึ่งกลาง ใช้white-space: nowrap;กับของคุณ<a>เพื่อหลีกเลี่ยงพฤติกรรมนี้
  • ต้องซ่อนคำแนะนำเครื่องมือก่อนที่จะลบองค์ประกอบที่เกี่ยวข้องออกจาก DOM
  • คำแนะนำเครื่องมือสามารถทริกเกอร์ได้ด้วยองค์ประกอบภายใน Shadow DOM

เอฟเฟกต์ภาพเคลื่อนไหวของส่วนประกอบนี้ขึ้นอยู่กับprefers-reduced-motionคิวรีสื่อ ดูส่วนการเคลื่อนไหวที่ลดลงของเอกสารการช่วยสำหรับการเข้าถึงของเรา

ได้ทั้งหมดที่? เยี่ยมมาก มาดูว่ามันทำงานอย่างไรพร้อมตัวอย่างบางส่วน

ตัวอย่าง: เปิดใช้งานคำแนะนำเครื่องมือทุกที่

วิธีหนึ่งในการเริ่มต้นคำแนะนำเครื่องมือทั้งหมดบนหน้าคือการเลือกตามdata-toggleแอตทริบิวต์:

$(function () {
  $('[data-toggle="tooltip"]').tooltip()
})

ตัวอย่าง

วางเมาส์เหนือลิงก์ด้านล่างเพื่อดูคำแนะนำเครื่องมือ:

กางเกงรัดรูป ระดับต่อไป keffiyeh คุณอาจไม่เคยได้ยินเกี่ยวกับพวกเขา บูธภาพถ่ายเคราผ้ายีนส์ดิบ letterpress กระเป๋าถือวีแก้น stumptown เครื่องแต่งกายแบบอเมริกันแบบ 8 บิตของ mcsweeney fixie ที่ยั่งยืนจากฟาร์มสู่โต๊ะมีผ้าแชมเบรย์ไวนิลริชาร์ดสันเทอร์รี่ Beard stumptown, เสื้อสเวตเตอร์ถัก banh mi lomo Thundercats เต้าหู้ไบโอดีเซล วิลเลี่ยมส์เบิร์ก มาร์ฟา, แชมเบรย์วีแก้นคลีนส์สี่โลโค แมคสวีนีย์ ช่างฝีมือที่น่าขันจริงๆไม่ว่า จะเป็นคีย์ตาร์ใดก็ตาม ทวิตเตอร์ ของ Austin จากฟาร์มถึงโต๊ะซึ่งจัดการไวรัสกาแฟต้นกำเนิดเดียวจากแหล่งเดียวของ freegan cred ฟรีแกน

วางเมาส์เหนือปุ่มด้านล่างเพื่อดูคำแนะนำเครื่องมือสี่ทิศทาง: บน ขวา ล่าง และซ้าย

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
  Tooltip on left
</button>

และด้วยการเพิ่ม HTML ที่กำหนดเอง:

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

การใช้งาน

ปลั๊กอินคำแนะนำเครื่องมือสร้างเนื้อหาและมาร์กอัปตามต้องการ และโดยค่าเริ่มต้นจะวางคำแนะนำเครื่องมือหลังองค์ประกอบทริกเกอร์

ทริกเกอร์คำแนะนำเครื่องมือผ่าน JavaScript:

$('#example').tooltip(options)
ล้นautoและscroll

ตำแหน่งคำแนะนำเครื่องมือพยายามเปลี่ยนโดยอัตโนมัติเมื่อคอนเทนเนอร์หลักมีoverflow: autoหรือoverflow: scrollเหมือนของเรา.table-responsiveแต่ยังคงตำแหน่งตำแหน่งเดิม ในการแก้ไข ให้ตั้งค่าboundaryตัวเลือกเป็นอย่างอื่นที่ไม่ใช่ค่าเริ่มต้น'scrollParent'เช่น'window':

$('#example').tooltip({ boundary: 'window' })

มาร์กอัป

มาร์กอัปที่จำเป็นสำหรับคำแนะนำเครื่องมือเป็นเพียงdataแอตทริบิวต์และtitleในองค์ประกอบ HTML ที่คุณต้องการให้มีคำแนะนำเครื่องมือ มาร์กอัปของคำแนะนำเครื่องมือที่สร้างขึ้นนั้นค่อนข้างง่าย แม้ว่าจะต้องมีตำแหน่ง (โดยค่าเริ่มต้น กำหนดtopโดยปลั๊กอิน)

การทำให้คำแนะนำเครื่องมือใช้งานได้สำหรับผู้ใช้คีย์บอร์ดและเทคโนโลยีช่วยเหลือ

คุณควรเพิ่มคำแนะนำเครื่องมือให้กับองค์ประกอบ HTML ที่เน้นคีย์บอร์ดและโต้ตอบได้ตามปกติ (เช่น ลิงก์หรือตัวควบคุมฟอร์ม) แม้ว่าองค์ประกอบ HTML ตามอำเภอใจ (เช่น<span>s) สามารถทำให้โฟกัสได้โดยการเพิ่มtabindex="0"แอตทริบิวต์ สิ่งนี้จะเพิ่มการหยุดแท็บที่อาจน่ารำคาญและทำให้เกิดความสับสนในองค์ประกอบที่ไม่โต้ตอบสำหรับผู้ใช้แป้นพิมพ์ และเทคโนโลยีช่วยเหลือส่วนใหญ่ในปัจจุบันยังไม่ประกาศคำแนะนำเครื่องมือในสถานการณ์นี้ นอกจากนี้ อย่าพึ่งเพียงhoverเป็นทริกเกอร์สำหรับคำแนะนำเครื่องมือของคุณ เนื่องจากจะทำให้คำแนะนำเครื่องมือของคุณไม่สามารถทริกเกอร์สำหรับผู้ใช้คีย์บอร์ดได้

<!-- HTML to write -->
<a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

องค์ประกอบพิการ

องค์ประกอบที่มีdisabledแอตทริบิวต์ไม่โต้ตอบ หมายความว่าผู้ใช้ไม่สามารถโฟกัส วางเมาส์เหนือ หรือคลิกเพื่อทริกเกอร์คำแนะนำเครื่องมือ (หรือป๊อปโอเวอร์) ในการแก้ปัญหาชั่วคราว คุณจะต้องทริกเกอร์คำแนะนำเครื่องมือจาก wrapper <div>หรือ<span>ทำให้แป้นพิมพ์โฟกัสได้โดยใช้tabindex="0"และแทนที่pointer-eventsองค์ประกอบบนที่ถูกปิดใช้งาน

<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

ตัวเลือก

ตัวเลือกสามารถส่งผ่านแอตทริบิวต์ข้อมูลหรือ JavaScript สำหรับแอ็ตทริบิวต์ data ให้ผนวกชื่ออ็อพชันต่อท้ายdata-เช่นเดียวกับในdata-animation="".

โปรดทราบว่าด้วยเหตุผลด้านความปลอดภัยsanitize, sanitizeFnและwhiteListตัวเลือกไม่สามารถระบุได้โดยใช้แอตทริบิวต์ข้อมูล

ชื่อ พิมพ์ ค่าเริ่มต้น คำอธิบาย
แอนิเมชั่น บูลีน จริง ใช้ CSS Fade Transition กับคำแนะนำเครื่องมือ
คอนเทนเนอร์ สตริง | องค์ประกอบ | เท็จ เท็จ

เพิ่มคำแนะนำเครื่องมือต่อท้ายองค์ประกอบเฉพาะ ตัวอย่าง: container: 'body'. ตัวเลือกนี้มีประโยชน์อย่างยิ่ง โดยจะช่วยให้คุณสามารถวางตำแหน่งคำแนะนำเครื่องมือในโฟลว์ของเอกสารใกล้กับองค์ประกอบการทริกเกอร์ ซึ่งจะป้องกันไม่ให้คำแนะนำเครื่องมือลอยออกจากองค์ประกอบที่ทริกเกอร์ในระหว่างการปรับขนาดหน้าต่าง
ล่าช้า หมายเลข | วัตถุ 0

ความล่าช้าในการแสดงและซ่อนคำแนะนำเครื่องมือ (ms) - ใช้ไม่ได้กับประเภททริกเกอร์ด้วยตนเอง

หากมีการระบุตัวเลข การหน่วงเวลาจะใช้กับทั้งซ่อน/แสดง

โครงสร้างวัตถุคือ:delay: { "show": 500, "hide": 100 }
html บูลีน เท็จ

อนุญาต HTML ในคำแนะนำเครื่องมือ

หากเป็นจริง แท็ก HTML ในคำแนะนำเครื่องมือtitleจะแสดงในคำแนะนำเครื่องมือ textหากเป็นเท็จ จะใช้วิธีของ jQuery เพื่อแทรกเนื้อหาลงใน DOM

ใช้ข้อความหากคุณกังวลเกี่ยวกับการโจมตี XSS
ตำแหน่ง สตริง | การทำงาน 'สูงสุด'

วิธีวางตำแหน่งคำแนะนำเครื่องมือ - auto | ด้านบน | ด้านล่าง | ซ้าย | ขวา.
เมื่อautoถูกระบุ มันจะปรับทิศทางคำแนะนำเครื่องมือใหม่แบบไดนามิก

เมื่อใช้ฟังก์ชันเพื่อกำหนดตำแหน่ง ฟังก์ชันนี้จะถูกเรียกโดยมีโหนด DOM ของคำแนะนำเครื่องมือเป็นอาร์กิวเมนต์แรก และโหนด DOM ที่ทริกเกอร์องค์ประกอบเป็นโหนดที่สอง thisบริบทถูกตั้งค่าเป็นอินสแตนซ์คำแนะนำเครื่องมือ
ตัวเลือก สตริง | เท็จ เท็จ หากมีตัวเลือก อ็อบเจ็กต์คำแนะนำเครื่องมือจะถูกส่งไปยังเป้าหมายที่ระบุ ในทางปฏิบัติ จะใช้เพื่อใช้คำแนะนำเครื่องมือกับองค์ประกอบ DOM ที่เพิ่มแบบไดนามิก ( jQuery.onการสนับสนุน) ดูสิ่งนี้และตัวอย่างข้อมูล
แม่แบบ สตริง '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

HTML พื้นฐานที่จะใช้เมื่อสร้างคำแนะนำเครื่องมือ

คำแนะนำเครื่องมือtitleจะถูกฉีดเข้าไปในไฟล์.tooltip-inner.

.arrowจะกลายเป็นลูกศรของคำแนะนำเครื่องมือ

องค์ประกอบ wrapper นอกสุดควรมี.tooltipคลาสและrole="tooltip".
ชื่อ สตริง | องค์ประกอบ | การทำงาน ''

ค่าเริ่มต้นของชื่อหากไม่มีtitleแอตทริบิวต์

หากมีการกำหนดฟังก์ชัน ฟังก์ชันนั้นจะถูกเรียกโดยthisตั้งค่าการอ้างอิงไปยังองค์ประกอบที่แนบคำแนะนำเครื่องมือ
สิ่งกระตุ้น สตริง 'เลื่อนโฟกัส'

วิธีการเรียกคำแนะนำเครื่องมือ - คลิก | โฉบ | โฟกัส | คู่มือ. คุณอาจส่งทริกเกอร์หลายตัว แยกพวกเขาด้วยช่องว่าง

'manual'ระบุว่าคำแนะนำเครื่องมือจะถูกเรียกใช้โดยทางโปรแกรมผ่านเมธอด.tooltip('show'), .tooltip('hide')และ .tooltip('toggle')ค่านี้ไม่สามารถรวมกับทริกเกอร์อื่นได้

'hover'ด้วยตัวมันเองจะส่งผลให้เกิดคำแนะนำเครื่องมือที่ไม่สามารถเรียกใช้ผ่านแป้นพิมพ์ได้ และควรใช้เฉพาะในกรณีที่มีวิธีการอื่นในการถ่ายทอดข้อมูลเดียวกันสำหรับผู้ใช้แป้นพิมพ์
offset หมายเลข | สตริง | การทำงาน 0

ออฟเซ็ตของคำแนะนำเครื่องมือที่สัมพันธ์กับเป้าหมาย

เมื่อใช้ฟังก์ชันเพื่อกำหนดออฟเซ็ต ฟังก์ชันจะถูกเรียกด้วยอ็อบเจ็กต์ที่มีข้อมูลออฟเซ็ตเป็นอาร์กิวเมนต์แรก ฟังก์ชันต้องส่งคืนวัตถุที่มีโครงสร้างเดียวกัน องค์ประกอบทริกเกอร์โหนด DOM ถูกส่งผ่านเป็นอาร์กิวเมนต์ที่สอง

สำหรับข้อมูลเพิ่มเติม โปรดดู เอกสารออฟเซ็ตของPopper.js
fallbackPlacement สตริง | อาร์เรย์ 'พลิก' อนุญาตให้ระบุตำแหน่งที่ Popper จะใช้กับทางเลือก สำหรับข้อมูลเพิ่มเติม โปรดดู เอกสารพฤติกรรมของ Popper.js
เขตแดน สตริง | ธาตุ 'เลื่อนผู้ปกครอง' ขอบเขตข้อจำกัดล้นของคำแนะนำเครื่องมือ ยอมรับค่าของ'viewport', 'window', 'scrollParent', หรือการอ้างอิง HTMLElement (JavaScript เท่านั้น) สำหรับข้อมูลเพิ่มเติม โปรดดู เอกสาร preventOverflow ของPopper.js
ฆ่าเชื้อ บูลีน จริง เปิดหรือปิดการฆ่าเชื้อ หากเปิดใช้งาน'template'และ'title'ตัวเลือกต่างๆ จะถูกฆ่าเชื้อ
whiteList วัตถุ ค่าเริ่มต้น ออบเจ็กต์ที่มีแอตทริบิวต์และแท็กที่อนุญาต
ฆ่าเชื้อFn null | การทำงาน โมฆะ ที่นี่คุณสามารถจัดหาฟังก์ชันฆ่าเชื้อของคุณเองได้ สิ่งนี้มีประโยชน์หากคุณต้องการใช้ห้องสมุดเฉพาะเพื่อทำการฆ่าเชื้อ
popperConfig null | วัตถุ โมฆะ หากต้องการเปลี่ยนการกำหนดค่า Popper.js เริ่มต้นของ Bootstrap โปรดดูการกำหนดค่าของ Popper.js

แอตทริบิวต์ข้อมูลสำหรับคำแนะนำเครื่องมือแต่ละรายการ

ตัวเลือกสำหรับคำแนะนำเครื่องมือแต่ละรายการสามารถระบุได้โดยใช้แอตทริบิวต์ข้อมูล ตามที่อธิบายข้างต้น

วิธีการ

วิธีการและการเปลี่ยนแบบอะซิงโครนัส

เมธอด API ทั้งหมดเป็นแบบอะซิงโครนัสและเริ่มต้นการเปลี่ยนแปลง พวกเขาจะกลับไปที่ผู้โทรทันทีที่เริ่มเปลี่ยน แต่ ก่อน ที่จะสิ้นสุด นอกจากนี้ การเรียกเมธอดบนคอมโพเนนต์การเปลี่ยนจะถูกละเว้น

ดูเอกสาร JavaScript ของเราสำหรับข้อมูลเพิ่มเติม

$().tooltip(options)

แนบตัวจัดการคำแนะนำเครื่องมือกับคอลเล็กชันองค์ประกอบ

.tooltip('show')

แสดงคำแนะนำเครื่องมือขององค์ประกอบ กลับไปยังผู้เรียกก่อนที่จะแสดงคำแนะนำเครื่องมือจริง (กล่าวคือ ก่อนที่shown.bs.tooltipเหตุการณ์จะเกิดขึ้น) นี่ถือเป็นการเรียกใช้ "คู่มือ" ของคำแนะนำเครื่องมือ คำแนะนำเครื่องมือที่มีชื่อความยาวเป็นศูนย์จะไม่แสดงขึ้น

$('#element').tooltip('show')

.tooltip('hide')

ซ่อนคำแนะนำเครื่องมือขององค์ประกอบ กลับไปยังผู้เรียกก่อนที่คำแนะนำเครื่องมือจะถูกซ่อนจริง ๆ (กล่าวคือ ก่อนที่hidden.bs.tooltipเหตุการณ์จะเกิดขึ้น) นี่ถือเป็นการเรียกใช้ "คู่มือ" ของคำแนะนำเครื่องมือ

$('#element').tooltip('hide')

.tooltip('toggle')

สลับคำแนะนำเครื่องมือขององค์ประกอบ กลับไปยังผู้เรียกก่อนที่จะแสดงหรือซ่อนคำแนะนำเครื่องมือจริง (เช่น ก่อนที่ เหตุการณ์ shown.bs.tooltipหรือhidden.bs.tooltipเหตุการณ์จะเกิดขึ้น) นี่ถือเป็นการเรียกใช้ "คู่มือ" ของคำแนะนำเครื่องมือ

$('#element').tooltip('toggle')

.tooltip('dispose')

ซ่อนและทำลายคำแนะนำขององค์ประกอบ คำแนะนำเครื่องมือที่ใช้การมอบหมาย (ซึ่งสร้างขึ้นโดยใช้ตัวselectorเลือก ) ไม่สามารถทำลายทีละรายการในองค์ประกอบทริกเกอร์ที่สืบทอดได้

$('#element').tooltip('dispose')

.tooltip('enable')

ให้ความสามารถในการแสดงคำแนะนำเครื่องมือขององค์ประกอบ คำแนะนำเครื่องมือเปิดใช้งานโดยค่าเริ่มต้น

$('#element').tooltip('enable')

.tooltip('disable')

ลบความสามารถในการแสดงคำแนะนำเครื่องมือขององค์ประกอบ คำแนะนำเครื่องมือจะแสดงได้ก็ต่อเมื่อเปิดใช้งานอีกครั้ง

$('#element').tooltip('disable')

.tooltip('toggleEnabled')

สลับความสามารถในการแสดงหรือซ่อนคำแนะนำเครื่องมือขององค์ประกอบ

$('#element').tooltip('toggleEnabled')

.tooltip('update')

อัปเดตตำแหน่งของคำแนะนำเครื่องมือขององค์ประกอบ

$('#element').tooltip('update')

เหตุการณ์

ประเภทงาน คำอธิบาย
show.bs.tooltip เหตุการณ์นี้จะเริ่มทำงานทันทีเมื่อมีshowการเรียกเมธอดของอินสแตนซ์
แสดง.bs.tooltip เหตุการณ์นี้เริ่มทำงานเมื่อผู้ใช้มองเห็นคำแนะนำเครื่องมือ (จะรอให้การเปลี่ยน CSS เสร็จสมบูรณ์)
hide.bs.tooltip เหตุการณ์นี้เริ่มทำงานทันทีเมื่อhideมีการเรียกเมธอดของอินสแตนซ์
hidden.bs.tooltip เหตุการณ์นี้เริ่มทำงานเมื่อคำแนะนำเครื่องมือถูกซ่อนจากผู้ใช้เสร็จสิ้น (จะรอให้การเปลี่ยน CSS เสร็จสมบูรณ์)
inserted.bs.tooltip เหตุการณ์นี้เริ่มทำงานหลังจากshow.bs.tooltipเหตุการณ์เมื่อมีการเพิ่มเทมเพลตคำแนะนำเครื่องมือใน DOM 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})