JavaScript

ทำให้ Bootstrap มีชีวิตชีวาด้วยปลั๊กอิน JavaScript เสริมของเรา เรียนรู้เกี่ยวกับปลั๊กอินแต่ละตัว ข้อมูลและตัวเลือก API แบบเป็นโปรแกรมของเรา และอื่นๆ

ในหน้านี้

บุคคลหรือรวบรวม

ปลั๊กอินสามารถรวมเป็นรายบุคคลได้ (โดยใช้บุคคลของ Bootstrap js/dist/*.js) หรือรวมเข้าด้วยกันโดยใช้bootstrap.jsหรือย่อขนาดbootstrap.min.js(ไม่รวมทั้งสองอย่าง)

หากคุณใช้เครื่องบันเดิล (Webpack, Parcel, Vite…) คุณสามารถใช้/js/dist/*.jsไฟล์ที่พร้อม UMD ได้

การใช้งานด้วยกรอบงาน JavaScript

แม้ว่า Bootstrap CSS จะใช้กับเฟรมเวิร์กใดก็ได้ แต่Bootstrap JavaScript ก็ไม่สามารถทำงานร่วมกับเฟรมเวิร์ก JavaScript ได้อย่างสมบูรณ์ เช่น React, Vue และ Angularซึ่งถือว่ามีความรู้เกี่ยวกับ DOM อย่างครบถ้วน ทั้ง Bootstrap และเฟรมเวิร์กอาจพยายามเปลี่ยนแปลงองค์ประกอบ DOM เดียวกัน ส่งผลให้เกิดบั๊ก เช่น ดรอปดาวน์ที่ติดอยู่ในตำแหน่ง "เปิด"

ทางเลือกที่ดีกว่าสำหรับผู้ที่ใช้เฟรมเวิร์กประเภทนี้คือการใช้แพ็คเกจเฉพาะเฟรมเวิร์กแทน Bootstrap JavaScript นี่คือตัวเลือกยอดนิยมบางส่วน:

ตอบสนอง: ตอบสนอง Bootstrap
Vue: BootstrapVue (ปัจจุบันรองรับเฉพาะ Vue 2 และ Bootstrap 4)
เชิงมุม: ng-bootstrap

การใช้ Bootstrap เป็นโมดูล

ลองด้วยตัวคุณเอง! ดาวน์โหลดซอร์สโค้ดและการสาธิตการใช้งาน Bootstrap เป็นโมดูล ES จากที่ เก็บtwbs/examples คุณยังสามารถ เปิดตัวอย่างใน StackBlitz

เรามีเวอร์ชันของ Bootstrap ที่สร้างเป็นESM( bootstrap.esm.jsและbootstrap.esm.min.js) ซึ่งช่วยให้คุณใช้ Bootstrap เป็นโมดูลในเบราว์เซอร์ได้ หากเบราว์เซอร์เป้าหมายของ คุณรองรับ

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

เมื่อเปรียบเทียบกับผู้บันเดิล JS การใช้ ESM ในเบราว์เซอร์จะทำให้คุณต้องใช้พาธแบบเต็มและชื่อไฟล์แทนชื่อโมดูล อ่านเพิ่มเติมเกี่ยวกับโมดูล JS ในเบราว์เซอร์ นั่นเป็นเหตุผลที่เราใช้'bootstrap.esm.min.js'แทน'bootstrap'ด้านบน อย่างไรก็ตาม สิ่งนี้ซับซ้อนมากขึ้นจากการพึ่งพา Popper ของเรา ซึ่งนำเข้า Popper ลงใน JavaScript ของเราดังนี้:

import * as Popper from "@popperjs/core"

หากคุณลองทำตามที่เป็นอยู่ คุณจะเห็นข้อผิดพลาดในคอนโซลดังนี้:

Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../".

ในการแก้ไขปัญหานี้ คุณสามารถใช้ an importmapเพื่อแก้ไขชื่อโมดูลโดยอำเภอใจเพื่อทำให้เส้นทางสมบูรณ์ หากเบราว์เซอร์เป้าหมาย ของคุณ ไม่รองรับimportmapคุณจะต้องใช้โปรเจ็กต์es-module-shims นี่คือวิธีการทำงานสำหรับ Bootstrap และ Popper:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-iYQeCzEYFbKjA/T2uDLTpkwGzCiq6soy8tYaI1GyVh/UjpbCx/TYkiZhlZB6+fzT" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="ESM in Browser" data-bs-content="Bang!">Custom popover</button>

    <script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
    <script type="importmap">
    {
      "imports": {
        "@popperjs/core": "https://cdn.jsdelivr.net/npm/@popperjs/[email protected]/dist/umd/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.esm.min.js"
      }
    }
    </script>
    <script type="module">
      import * as bootstrap from 'bootstrap'

      new bootstrap.Popover(document.getElementById('popoverButton'))
    </script>
  </body>
</html>

การพึ่งพา

ปลั๊กอินและส่วนประกอบ CSS บางตัวขึ้นอยู่กับปลั๊กอินอื่นๆ หากคุณรวมปลั๊กอินแต่ละรายการ ตรวจสอบให้แน่ใจว่าได้ตรวจสอบการขึ้นต่อกันเหล่านี้ในเอกสาร

ดรอปดาวน์ ป๊อปโอเวอร์ และคำแนะนำเครื่องมือของเราก็ขึ้นอยู่กับPopperด้วย

แอตทริบิวต์ข้อมูล

ปลั๊กอิน Bootstrap เกือบทั้งหมดสามารถเปิดใช้งานและกำหนดค่าผ่าน HTML เพียงอย่างเดียวด้วยแอตทริบิวต์ข้อมูล (วิธีที่เราต้องการในการใช้ฟังก์ชัน JavaScript) ตรวจสอบให้แน่ใจว่าใช้แอตทริบิวต์ข้อมูลเพียงชุดเดียวในองค์ประกอบเดียว (เช่น คุณไม่สามารถเรียกใช้คำแนะนำเครื่องมือและโมดอลจากปุ่มเดียวกันได้)

เนื่องจากตัวเลือกสามารถส่งผ่านแอตทริบิวต์ข้อมูลหรือ JavaScript คุณจึงเพิ่มชื่อตัวเลือกต่อท้ายได้ เช่น เดียวdata-bs-กับใน data-bs-animation="{value}"ตรวจสอบให้แน่ใจว่าได้เปลี่ยนประเภทเคสของชื่อตัวเลือกจาก “ camelCase ” เป็น “ kebab-case ” เมื่อส่งตัวเลือกผ่านแอตทริบิวต์ data เช่น ใช้data-bs-custom-class="beautifier"แทนdata-bs-customClass="beautifier".

ใน Bootstrap 5.2.0 ส่วนประกอบทั้งหมดสนับสนุนแอตทริบิวต์ข้อมูลที่สงวนไว้สำหรับทดลองdata-bs-configซึ่งสามารถจัดเก็บการกำหนดค่าส่วนประกอบอย่างง่ายเป็นสตริง JSON เมื่อองค์ประกอบมีdata-bs-config='{"delay":0, "title":123}'และdata-bs-title="456"แอตทริบิวต์ ค่าสุดท้ายtitleจะเป็น456และแอตทริบิวต์ข้อมูลที่แยกจากกันจะแทนที่ค่าที่ให้ไว้data-bs-configใน นอกจากนี้ แอตทริบิวต์ข้อมูลที่มีอยู่ยังสามารถเก็บค่า JSON เช่นdata-bs-delay='{"show":0,"hide":150}'.

ตัวเลือก

เราใช้เนที ฟ querySelectorและquerySelectorAllวิธีการค้นหาองค์ประกอบ DOM ด้วยเหตุผลด้านประสิทธิภาพ ดังนั้นคุณต้องใช้ตัวเลือกที่ถูกต้อง หากคุณใช้ตัวเลือกพิเศษเช่นcollapse:Exampleอย่าลืมหลีกเลี่ยง

เหตุการณ์

Bootstrap จัดเตรียมเหตุการณ์ที่กำหนดเองสำหรับการกระทำเฉพาะของปลั๊กอินส่วนใหญ่ โดยทั่วไป สิ่งเหล่านี้มาในรูปแบบกริยาแบบ infinitive และ past participle โดยที่ infinitive (เช่นshow) จะถูกทริกเกอร์เมื่อเริ่มต้นเหตุการณ์ และรูปแบบกริยาที่ผ่านมา (ex. shown) จะถูกทริกเกอร์เมื่อการดำเนินการเสร็จสิ้น

เหตุการณ์ infinitive ทั้งหมดมีpreventDefault()ฟังก์ชันการทำงาน สิ่งนี้ทำให้สามารถหยุดการดำเนินการก่อนที่จะเริ่ม การคืน ค่าเท็จจากตัวจัดการเหตุการณ์จะเรียกโดยอัตโนมัติpreventDefault()ด้วย

const myModal = document.querySelector('#myModal')

myModal.addEventListener('show.bs.modal', event => {
  if (!data) {
    return event.preventDefault() // stops modal from being shown
  }
})

API แบบเป็นโปรแกรม

ตัวสร้างทั้งหมดยอมรับอ็อบเจ็กต์ตัวเลือกที่เป็นตัวเลือกหรือไม่มีเลย (ซึ่งเริ่มต้นปลั๊กอินด้วยการทำงานเริ่มต้น):

const myModalEl = document.querySelector('#myModal')

const modal = new bootstrap.Modal(myModalEl) // initialized with defaults

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // initialized with no keyboard

หากคุณต้องการได้รับอินสแตนซ์ของปลั๊กอินบางตัว ปลั๊กอินแต่ละตัวจะแสดงgetInstanceวิธีการ ตัวอย่างเช่น ในการดึงข้อมูลอินสแตนซ์โดยตรงจากองค์ประกอบ:

bootstrap.Popover.getInstance(myPopoverEl)

เมธอดนี้จะส่งคืนnullหากไม่มีการเริ่มต้นอินสแตนซ์เหนือองค์ประกอบที่ร้องขอ

อีกทางหนึ่งgetOrCreateInstanceสามารถใช้เพื่อรับอินสแตนซ์ที่เชื่อมโยงกับองค์ประกอบ DOM หรือสร้างใหม่ในกรณีที่ไม่ได้เริ่มต้น

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

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

ตัวเลือก CSS ในตัวสร้าง

นอกเหนือจาก เมธอด getInstanceและgetOrCreateInstanceเมธอด ตัวสร้างปลั๊กอินทั้งหมดสามารถยอมรับองค์ประกอบ DOM หรือตัวเลือก CSS ที่ถูกต้อง เป็นอาร์กิวเมนต์แรกได้ พบองค์ประกอบของปลั๊กอินด้วยquerySelectorวิธีดังกล่าว เนื่องจากปลั๊กอินของเราสนับสนุนเพียงองค์ประกอบเดียวเท่านั้น

const modal = new bootstrap.Modal('#myModal')
const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas')
const alert = bootstrap.Alert.getOrCreateInstance('#myAlert')

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

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

const myCollapseEl = document.querySelector('#myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // Action to execute once the collapsible area is expanded
})

นอกจากนี้ การเรียกเมธอดบนคอมโพเนนต์การเปลี่ยนจะถูกละเว้น

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})

carousel.to('1') // Will start sliding to the slide 1 and returns to the caller
carousel.to('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!

`dispose`กระบวนการ

disposeแม้ว่าการใช้ วิธีการทันทีหลังจากนี้อาจดูเหมือนถูกต้องhide()แต่จะนำไปสู่ผลลัพธ์ที่ไม่ถูกต้อง ต่อไปนี้คือตัวอย่างการใช้ปัญหา:

const myModal = document.querySelector('#myModal')
myModal.hide() // it is asynchronous

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

การตั้งค่าเริ่มต้น

คุณสามารถเปลี่ยนการตั้งค่าเริ่มต้นสำหรับปลั๊กอินโดยแก้ไขConstructor.Defaultวัตถุของปลั๊กอิน:

// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false

วิธีการและคุณสมบัติ

ปลั๊กอิน Bootstrap ทุกตัวจะแสดงเมธอดและคุณสมบัติสแตติกต่อไปนี้

วิธี	คำอธิบาย
`dispose`	ทำลายโมดอลขององค์ประกอบ (ลบ��้อมูลที่เก็บไว้ในองค์ประกอบ DOM)
`getInstance`	วิธีการ แบบคงที่ซึ่งช่วยให้คุณได้รับอินสแตนซ์โมดอลที่เชื่อมโยงกับองค์ประกอบ DOM
`getOrCreateInstance`	เมธอด แบบคงที่ซึ่งช่วยให้คุณได้รับโมดอลอินสแตนซ์ที่เชื่อมโยงกับองค์ประกอบ DOM หรือสร้างใหม่ในกรณีที่ไม่ได้เริ่มต้น

คุณสมบัติคงที่	คำอธิบาย
`NAME`	ส่งกลับชื่อปลั๊กอิน (ตัวอย่าง: `bootstrap.Tooltip.NAME`)
`VERSION`	เวอร์ชันของปลั๊กอินแต่ละปลั๊กอินของ Bootstrap สามารถเข้าถึงได้ผ่าน`VERSION`คุณสมบัติของตัวสร้างของปลั๊กอิน (ตัวอย่าง: `bootstrap.Tooltip.VERSION`)

น้ำยาฆ่าเชื้อ

คำแนะนำเครื่องมือและ Popovers ใช้น้ำยาฆ่าเชื้อในตัวของเราเพื่อล้างตัวเลือกที่ยอมรับ HTML

ค่าเริ่มต้นallowListมีดังต่อไปนี้:

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
const DefaultAllowlist = {
  // Global attributes allowed on any supplied element below.
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  div: [],
  em: [],
  hr: [],
  h1: [],
  h2: [],
  h3: [],
  h4: [],
  h5: [],
  h6: [],
  i: [],
  img: ['src', 'srcset', 'alt', 'title', 'width', 'height'],
  li: [],
  ol: [],
  p: [],
  pre: [],
  s: [],
  small: [],
  span: [],
  sub: [],
  sup: [],
  strong: [],
  u: [],
  ul: []
}

หากคุณต้องการเพิ่มค่าใหม่ให้กับค่าเริ่มต้นนี้allowListคุณสามารถดำเนินการดังต่อไปนี้:

const myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// To allow table elements
myDefaultAllowList.table = []

// To allow td elements and data-bs-option attributes on td elements
myDefaultAllowList.td = ['data-bs-option']

// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
const myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

หากคุณต้องการเลี่ยงการฆ่าเชื้อของเรา เนื่องจากคุณต้องการใช้ห้องสมุดเฉพาะ เช่นDOMPurifyคุณควรดำเนินการดังต่อไปนี้:

const yourTooltipEl = document.querySelector('#yourTooltip')
const tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn(content) {
    return DOMPurify.sanitize(content)
  }
})

เลือกใช้ jQuery

คุณไม่ต้องการ jQuery ใน Bootstrap 5แต่ก็ยังสามารถใช้ส่วนประกอบของเรากับ jQuery หาก Bootstrap ตรวจพบjQueryในwindowวัตถุ มันจะเพิ่มส่วนประกอบทั้งหมดของเราในระบบปลั๊กอินของ jQuery ซึ่งช่วยให้คุณทำสิ่งต่อไปนี้ได้:

$('[data-bs-toggle="tooltip"]').tooltip() // to enable tooltips, with default configuration

$('[data-bs-toggle="tooltip"]').tooltip({ boundary: 'clippingParents', customClass: 'myClass' }) // to initialize tooltips with given configuration

$('#myTooltip').tooltip('show') // to trigger `show` method

เช่นเดียวกับองค์ประกอบอื่นๆ ของเรา

ไม่มีความขัดแย้ง

บางครั้ง จำเป็นต้องใช้ปลั๊กอิน Bootstrap กับเฟรมเวิร์ก UI อื่นๆ ในสถานการณ์เหล่านี้ การชนกันของเนมสเปซอาจเกิดขึ้นในบางครั้ง หากเกิดเหตุการณ์นี้ขึ้น คุณสามารถเรียก.noConflictใช้ปลั๊กอินที่คุณต้องการคืนค่า

const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality

Bootstrap ไม่รองรับไลบรารี JavaScript ของบุคคลที่สามเช่น Prototype หรือ jQuery UI อย่างเป็นทางการ แม้ว่า.noConflictเหตุการณ์เนมสเปซและเนมสเปซอาจมีปัญหาความเข้ากันได้ซึ่งคุณต้องแก้ไขด้วยตัวเอง

เหตุการณ์ jQuery

Bootstrap จะตรวจจับ jQuery หากjQueryมีอยู่ในwindowวัตถุและไม่มีการdata-bs-no-jqueryตั้งค่าแอตทริบิวต์<body>ไว้ หากพบ jQuery Bootstrap จะปล่อยเหตุการณ์ด้วยระบบเหตุการณ์ของ jQuery ดังนั้น หากคุณต้องการฟังเหตุการณ์ของ Bootstrap คุณจะต้องใช้เมธอด jQuery ( .on, .one) แทนaddEventListener.

$('#myTab a').on('shown.bs.tab', () => {
  // do something...
})

JavaScript ปิดการใช้งาน

ปลั๊กอินของ Bootstrap ไม่มีทางเลือกพิเศษเมื่อปิดใช้งาน JavaScript หากคุณสนใจเกี่ยวกับประสบการณ์ของผู้ใช้ในกรณีนี้ ใช้<noscript>เพื่ออธิบายสถานการณ์ (และวิธีเปิดใช้งาน JavaScript อีกครั้ง) ให้กับผู้ใช้ของคุณ และ/หรือเพิ่มทางเลือกที่คุณกำหนดเอง