in English

JavaScript

Mang Bootstrap vào cuộc sống với các plugin JavaScript tùy ch��n của chúng tôi. Tìm hiểu về từng plugin, dữ liệu và các tùy chọn API có lập trình của chúng tôi, v.v.

Trên trang này

Cá nhân hoặc tổng hợp

Các plugin có thể được bao gồm riêng lẻ (sử dụng Bootstrap riêng lẻ js/dist/*.js), hoặc sử dụng tất cả cùng một lúc bootstrap.jshoặc được rút gọn bootstrap.min.js(không bao gồm cả hai).

Nếu bạn sử dụng một gói (Webpack, Parcel, Vite…), bạn có thể sử dụng /js/dist/*.jscác tệp đã sẵn sàng cho UMD.

Sử dụng với các khung JavaScript

Mặc dù Bootstrap CSS có thể được sử dụng với bất kỳ khung công tác nào, nhưng Bootstrap JavaScript không hoàn toàn tương thích với các khung công tác JavaScript như React, Vue và Angular vốn có kiến thức đầy đủ về DOM. Cả Bootstrap và khung công tác đều có thể cố gắng thay đổi cùng một phần tử DOM, dẫn đến các lỗi như trình đơn thả xuống bị kẹt ở vị trí “mở”.

Một giải pháp thay thế tốt hơn cho những người sử dụng loại khung công tác này là sử dụng gói dành riêng cho khung công tác thay vì JavaScript Bootstrap. Dưới đây là một số tùy chọn phổ biến nhất:

React: React Bootstrap
Vue: BootstrapVue (hiện chỉ hỗ trợ Vue 2 và Bootstrap 4)
Angular: ng-bootstrap

Sử dụng Bootstrap làm mô-đun

Hãy thử nó cho mình! Tải xuống mã nguồn và bản trình diễn hoạt động để sử dụng Bootstrap làm mô-đun ES từ kho lưu trữ twbs /amples . Bạn cũng có thể mở ví dụ trong StackBlitz .

Chúng tôi cung cấp phiên bản Bootstrap được xây dựng dưới dạng ESM( bootstrap.esm.jsvà bootstrap.esm.min.js) cho phép bạn sử dụng Bootstrap làm mô-đun trong trình duyệt, nếu các trình duyệt được nhắm mục tiêu của bạn hỗ trợ nó .

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

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

So với các gói JS, việc sử dụng ESM trong trình duyệt yêu cầu bạn sử dụng đường dẫn đầy đủ và tên tệp thay vì tên mô-đun. Đọc thêm về mô-đun JS trong trình duyệt. Đó là lý do tại sao chúng tôi sử dụng 'bootstrap.esm.min.js'thay vì 'bootstrap'ở trên. Tuy nhiên, điều này còn phức tạp hơn bởi sự phụ thuộc vào Popper của chúng tôi, nhập Popper vào JavaScript của chúng tôi như sau:

import * as Popper from "@popperjs/core"

Nếu bạn thử nguyên trạng này, bạn sẽ thấy lỗi trong bảng điều khiển như sau:

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

Để khắc phục điều này, bạn có thể sử dụng một importmapđể phân giải các tên mô-đun tùy ý để hoàn thành các đường dẫn. Nếu các trình duyệt được nhắm mục tiêu của bạn không hỗ trợ importmap, bạn sẽ cần sử dụng dự án es-module-shims . Đây là cách nó hoạt động cho Bootstrap và 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>

Sự phụ thuộc

Một số plugin và thành phần CSS phụ thuộc vào các plugin khác. Nếu bạn bao gồm các plugin riêng lẻ, hãy đảm bảo kiểm tra các phần phụ thuộc này trong tài liệu.

Trình đơn thả xuống, cửa sổ bật lên và chú giải công cụ của chúng tôi cũng phụ thuộc vào Popper .

Thuộc tính dữ liệu

Gần như tất cả các plugin Bootstrap đều có thể được kích hoạt và định cấu hình chỉ thông qua HTML với các thuộc tính dữ liệu (cách ưa thích của chúng tôi khi sử dụng chức năng JavaScript). Đảm bảo chỉ sử dụng một tập hợp các thuộc tính dữ liệu trên một phần tử (ví dụ: bạn không thể kích hoạt chú giải công cụ và phương thức từ cùng một nút.)

Vì các tùy chọn có thể được chuyển qua thuộc tính dữ liệu hoặc JavaScript, bạn có thể thêm tên tùy chọn vào data-bs-, như trong data-bs-animation="{value}". Đảm bảo thay đổi kiểu chữ hoa của tên tùy chọn từ “ camelCase ” thành “ kebab-case ” khi chuyển các tùy chọn qua thuộc tính dữ liệu. Ví dụ, sử dụng data-bs-custom-class="beautifier"thay vì data-bs-customClass="beautifier".

Kể từ Bootstrap 5.2.0, tất cả các thành phần đều hỗ trợ thuộc tính dữ liệu dành riêng thử nghiệmdata-bs-config có thể chứa cấu hình thành phần đơn giản dưới dạng chuỗi JSON. Khi một phần tử có data-bs-config='{"delay":0, "title":123}'và data-bs-title="456"các thuộc tính, titlegiá trị cuối cùng sẽ là 456và các thuộc tính dữ liệu riêng biệt sẽ ghi đè các giá trị được cho trên data-bs-config. Ngoài ra, các thuộc tính dữ liệu hiện có có thể chứa các giá trị JSON như data-bs-delay='{"show":0,"hide":150}'.

Bộ chọn

Chúng tôi sử dụng các phương pháp querySelectorvà nguyên gốc querySelectorAllđể truy vấn các phần tử DOM vì lý do hiệu suất, vì vậy bạn phải sử dụng các bộ chọn hợp lệ . Nếu bạn sử dụng các bộ chọn đặc biệt như collapse:Example, hãy đảm bảo thoát khỏi chúng.

Sự kiện

Bootstrap cung cấp các sự kiện tùy chỉnh cho hầu hết các hành động độc đáo của plugin. Nói chung, chúng có dạng phân từ nguyên thể và quá khứ - trong đó nguyên thể (ví dụ show) được kích hoạt khi bắt đầu một sự kiện và dạng phân từ trong quá khứ của nó (ví dụ shown) được kích hoạt khi hoàn thành một hành động.

Tất cả các sự kiện vô tận đều cung cấp preventDefault()chức năng. Điều này cung cấp khả năng dừng thực hiện một hành động trước khi nó bắt đầu. Trả về false từ một trình xử lý sự kiện cũng sẽ tự động gọi preventDefault().

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

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

API có lập trình

Tất cả các hàm tạo đều chấp nhận một đối tượng tùy chọn tùy chọn hoặc không có gì (khởi tạo một plugin với hành vi mặc định của nó):

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

Nếu bạn muốn nhận một phiên bản plugin cụ thể, mỗi plugin sẽ hiển thị một getInstancephương pháp. Ví dụ, để truy xuất một thể hiện trực tiếp từ một phần tử:

bootstrap.Popover.getInstance(myPopoverEl)

Phương thức này sẽ trả về nullnếu một thể hiện không được khởi tạo trên phần tử được yêu cầu.

Ngoài ra, getOrCreateInstancecó thể được sử dụng để lấy phiên bản được liên kết với phần tử DOM hoặc tạo một phiên bản mới trong trường hợp nó chưa được khởi tạo.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Trong trường hợp một phiên bản không được khởi tạo, nó có thể chấp nhận và sử dụng một đối tượng cấu hình tùy chọn làm đối số thứ hai.

Bộ chọn CSS trong trình tạo

Ngoài các phương thức getInstancevà getOrCreateInstance, tất cả các trình tạo plugin có thể chấp nhận một phần tử DOM hoặc một bộ chọn CSS hợp lệ làm đối số đầu tiên. Các phần tử plugin được tìm thấy bằng querySelectorphương pháp này vì các plugin của chúng tôi chỉ hỗ trợ một phần tử duy nhất.

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')

Các chức năng và chuyển tiếp không đồng bộ

Tất cả các phương thức API có lập trình là không đồng bộ và trở lại trình gọi khi quá trình chuyển đổi được bắt đầu, nhưng trước khi quá trình chuyển đổi kết thúc . Để thực hiện một hành động sau khi quá trình chuyển đổi hoàn tất, bạn có thể lắng nghe sự kiện tương ứng.

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

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

Ngoài ra, một lệnh gọi phương thức trên một thành phần chuyển tiếp sẽ bị bỏ qua .

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`phương pháp

Mặc dù có vẻ đúng nếu sử dụng disposephương pháp ngay sau hide()đó, nhưng nó sẽ dẫn đến kết quả không chính xác. Đây là một ví dụ về vấn đề sử dụng:

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

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

Thiết lập mặc định

Bạn có thể thay đổi cài đặt mặc định cho plugin bằng cách sửa đổi Constructor.Defaultđối tượng của plugin:

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

Phương pháp và thuộc tính

Mọi plugin Bootstrap đều hiển thị các phương thức và thuộc tính tĩnh sau đây.

Phương pháp	Sự mô tả
`dispose`	Phá hủy phương thức của một phần tử. (Xóa dữ liệu được lưu trữ trên phần tử DOM)
`getInstance`	Phương thức tĩnh cho phép bạn lấy thể hiện phương thức được liên kết với một phần tử DOM.
`getOrCreateInstance`	Phương thức tĩnh cho phép bạn lấy thể hiện phương thức được liên kết với một phần tử DOM hoặc tạo một thể hiện mới trong trường hợp nó chưa được khởi tạo.

Thuộc tính tĩnh	Sự mô tả
`NAME`	Trả về tên plugin. (Ví dụ `bootstrap.Tooltip.NAME`:)
`VERSION`	Phiên bản của mỗi plugin Bootstrap có thể được truy cập thông qua thuộc `VERSION`tính của hàm tạo của plugin (Ví dụ `bootstrap.Tooltip.VERSION`:)

Chất tẩy rửa

Chú giải công cụ và Trình mở rộng sử dụng trình khử trùng tích hợp của chúng tôi để khử trùng các tùy chọn chấp nhận HTML.

Giá trị mặc định allowListnhư sau:

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: []
}

Nếu bạn muốn thêm các giá trị mới vào mặc định này, allowListbạn có thể làm như sau:

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)

Nếu bạn muốn bỏ qua trình khử trùng của chúng tôi vì bạn thích sử dụng một thư viện chuyên dụng, chẳng hạn như DOMPurify , bạn nên làm như sau:

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

Tùy chọn sử dụng jQuery

Bạn không cần jQuery trong Bootstrap 5 , nhưng vẫn có thể sử dụng các thành phần của chúng tôi với jQuery. Nếu Bootstrap phát hiện jQuerytrong windowđối tượng, nó sẽ thêm tất cả các thành phần của chúng tôi vào hệ thống plugin của jQuery. Điều này cho phép bạn làm những việc sau:

$('[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

Tương tự với các thành phần khác của chúng ta.

Không có xung đột

Đôi khi cần sử dụng các plugin Bootstrap với các khung giao diện người dùng khác. Trong những trường hợp này, đôi khi có thể xảy ra xung đột không gian tên. Nếu điều này xảy ra, bạn có thể gọi .noConflictplugin mà bạn muốn hoàn nguyên giá trị.

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

Bootstrap không chính thức hỗ trợ các thư viện JavaScript của bên thứ ba như Prototype hoặc jQuery UI. Bất chấp .noConflictvà các sự kiện không gian tên, có thể có các vấn đề tương thích mà bạn cần tự khắc phục.

sự kiện jQuery

Bootstrap sẽ phát hiện jQuery nếu jQuerycó trong windowđối tượng và không có data-bs-no-jquerythuộc tính nào được đặt trên <body>. Nếu jQuery được tìm thấy, Bootstrap sẽ phát ra các sự kiện nhờ hệ thống sự kiện của jQuery. Vì vậy, nếu bạn muốn nghe các sự kiện của Bootstrap, bạn sẽ phải sử dụng các phương thức jQuery ( .on, .one) thay vì addEventListener.

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

JavaScript bị tắt

Các plugin của Bootstrap không có dự phòng đặc biệt khi JavaScript bị tắt. Nếu bạn quan tâm đến trải nghiệm người dùng trong trường hợp này, hãy sử dụng <noscript>để giải thích tình huống (và cách bật lại JavaScript) cho người dùng của bạn và / hoặc thêm các dự phòng tùy chỉnh của riêng bạn.