JavaScript

Ożyw Bootstrap za pomocą naszych opcjonalnych wtyczek JavaScript. Dowiedz się więcej o każdej wtyczce, naszych danych i opcjach programistycznych interfejsów API i nie tylko.

Na tej stronie

Indywidualne lub skompilowane

Wtyczki mogą być dołączane pojedynczo (za pomocą funkcji Bootstrap's individual js/dist/*.js) lub wszystkie naraz za pomocą bootstrap.jslub zminimalizowane bootstrap.min.js(nie uwzględniaj obu).

Jeśli używasz bundlera (Webpack, Parcel, Vite…), możesz użyć /js/dist/*.jsplików gotowych do UMD.

Wykorzystanie z frameworkami JavaScript

Podczas gdy Bootstrap CSS może być używany z dowolnym frameworkiem, Bootstrap JavaScript nie jest w pełni kompatybilny z frameworkami JavaScript, takimi jak React, Vue i Angular, które zakładają pełną znajomość DOM. Zarówno Bootstrap, jak i framework mogą próbować zmutować ten sam element DOM, co skutkuje błędami, takimi jak listy rozwijane, które utknęły w pozycji „otwarte”.

Lepszą alternatywą dla tych, którzy używają tego typu frameworków, jest użycie pakietu specyficznego dla frameworka zamiast Bootstrap JavaScript. Oto niektóre z najpopularniejszych opcji:

React: React Bootstrap
Vue: BootstrapVue (obecnie obsługuje tylko Vue 2 i Bootstrap 4)
Angular: ng-bootstrap

Używanie Bootstrapa jako modułu

Spróbuj sam! Pobierz kod źródłowy i działające demo do używania Bootstrap jako modułu ES z repozytorium twbs/examples . Możesz również otworzyć przykład w StackBlitz .

Dostarczamy wersję Bootstrap zbudowaną jako ESM( bootstrap.esm.jsi bootstrap.esm.min.js), która pozwala na używanie Bootstrap jako modułu w przeglądarce, jeśli Twoje docelowe przeglądarki obsługują to .

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

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

W porównaniu z pakietami JS, używanie ESM w przeglądarce wymaga użycia pełnej ścieżki i nazwy pliku zamiast nazwy modułu. Przeczytaj więcej o modułach JS w przeglądarce. Dlatego używamy 'bootstrap.esm.min.js'zamiast 'bootstrap'powyższego. Jednak jest to jeszcze bardziej skomplikowane przez naszą zależność Poppera, która importuje Poppera do naszego JavaScriptu w następujący sposób:

import * as Popper from "@popperjs/core"

Jeśli spróbujesz tego bez zmian, zobaczysz w konsoli błąd podobny do następującego:

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

Aby to naprawić, możesz użyć , importmapaby rozwiązać arbitralne nazwy modułów na pełne ścieżki. Jeśli docelowe przeglądarki nie obsługują importmap, musisz użyć projektu es-module-shims . Oto jak to działa w przypadku Bootstrapa i Poppera:

<!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>

Zależności

Niektóre wtyczki i komponenty CSS zależą od innych wtyczek. Jeśli dołączasz wtyczki pojedynczo, sprawdź te zależności w dokumentach.

Nasze listy rozwijane, okienka wyskakujące i podpowiedzi również zależą od Poppera .

Atrybuty danych

Prawie wszystkie wtyczki Bootstrap można włączyć i skonfigurować za pomocą samego HTML z atrybutami danych (nasz preferowany sposób korzystania z funkcji JavaScript). Upewnij się, że używasz tylko jednego zestawu atrybutów danych na pojedynczym elemencie (np. nie możesz wywołać podpowiedzi i modalnej z tego samego przycisku).

Ponieważ opcje mogą być przekazywane przez atrybuty danych lub JavaScript, możesz dołączyć nazwę opcji do data-bs-, jak w data-bs-animation="{value}". Pamiętaj, aby zmienić typ wielkości liter w nazwie opcji z „ camelCase ” na „ kebab-case ” podczas przekazywania opcji przez atrybuty danych. Na przykład użyj data-bs-custom-class="beautifier"zamiast data-bs-customClass="beautifier".

Od wersji Bootstrap 5.2.0 wszystkie komponenty obsługują eksperymentalny atrybut zarezerwowanych danych data-bs-config, który może zawierać prostą konfigurację komponentu w postaci ciągu JSON. Gdy element ma atrybuty data-bs-config='{"delay":0, "title":123}'i data-bs-title="456", ostateczną titlewartością będzie, 456a oddzielne atrybuty danych zastąpią wartości podane w data-bs-config. Ponadto istniejące atrybuty danych mogą zawierać wartości JSON, takie jak data-bs-delay='{"show":0,"hide":150}'.

Selektory

Używamy metod natywnych querySelectori querySelectorAllmetod do tworzenia zapytań o elementy DOM ze względu na wydajność, dlatego musisz używać prawidłowych selektorów . Jeśli używasz specjalnych selektorów, takich jak collapse:Example, pamiętaj o ich ominięciu.

Wydarzenia

Bootstrap zapewnia niestandardowe zdarzenia dla większości unikalnych działań wtyczek. Ogólnie rzecz biorąc, mają one formę bezokolicznika i imiesłowu przeszłego - gdzie bezokolicznik (np. show) jest wyzwalany na początku zdarzenia, a jego forma imiesłowu przeszłego (np. shown) jest wyzwalana po zakończeniu działania.

Wszystkie zdarzenia bezokolicznikowe zapewniają preventDefault()funkcjonalność. Daje to możliwość zatrzymania wykonywania akcji przed jej rozpoczęciem. Zwrócenie false z programu obsługi zdarzeń również spowoduje automatyczne wywołanie preventDefault().

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

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

Programowy interfejs API

Wszystkie konstruktory akceptują opcjonalny obiekt opcji lub nic (co inicjuje wtyczkę z jej domyślnym zachowaniem):

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

Jeśli chcesz uzyskać konkretną instancję wtyczki, każda wtyczka udostępnia getInstancemetodę. Na przykład, aby pobrać instancję bezpośrednio z elementu:

bootstrap.Popover.getInstance(myPopoverEl)

Ta metoda zwróci null, jeśli wystąpienie nie zostanie zainicjowane w żądanym elemencie.

Alternatywnie getOrCreateInstancemoże służyć do pobrania instancji powiązanej z elementem DOM lub utworzenia nowego, na wypadek gdyby nie został zainicjowany.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

W przypadku, gdy instancja nie została zainicjowana, może zaakceptować i użyć opcjonalnego obiektu konfiguracyjnego jako drugiego argumentu.

Selektory CSS w konstruktorach

Oprócz metod getInstancei getOrCreateInstancewszystkie konstruktory wtyczek mogą akceptować element DOM lub prawidłowy selektor CSS jako pierwszy argument. W metodzie znajdują się elementy querySelectorwtyczek, ponieważ nasze wtyczki obsługują tylko jeden element.

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

Funkcje asynchroniczne i przejścia

Wszystkie metody programistycznego interfejsu API są asynchroniczne i wracają do obiektu wywołującego po rozpoczęciu przejścia, ale przed jego zakończeniem . Aby wykonać akcję po zakończeniu przejścia, możesz odsłuchać odpowiednie zdarzenie.

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

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

Ponadto wywołanie metody na składniku przechodzącym zostanie zignorowane .

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`metoda

disposeChociaż użycie tej metody natychmiast po użyciu może wydawać się poprawne hide(), spowoduje to uzyskanie nieprawidłowych wyników. Oto przykład użycia problemu:

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

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

Ustawienia domyślne

Możesz zmienić domyślne ustawienia wtyczki, modyfikując Constructor.Defaultobiekt wtyczki:

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

Metody i właściwości

Każda wtyczka Bootstrap udostępnia następujące metody i właściwości statyczne.

metoda	Opis
`dispose`	Niszczy modalny elementu. (Usuwa dane zapisane w elemencie DOM)
`getInstance`	Metoda statyczna , która pozwala uzyskać instancję modalną skojarzoną z elementem DOM.
`getOrCreateInstance`	Metoda statyczna , która pozwala uzyskać instancję modalną skojarzoną z elementem DOM lub utworzyć nową w przypadku, gdy nie została zainicjowana.

Właściwość statyczna	Opis
`NAME`	Zwraca nazwę wtyczki. (Przykład: `bootstrap.Tooltip.NAME`)
`VERSION`	Dostęp do wersji każdej z wtyczek Bootstrap można uzyskać za pośrednictwem `VERSION`właściwości konstruktora wtyczki (Przykład: `bootstrap.Tooltip.VERSION`)

Odkażacz

Etykietki narzędzi i popovery używają naszego wbudowanego narzędzia do czyszczenia, aby oczyścić opcje, które akceptują HTML.

Wartość domyślna allowListjest następująca:

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

Jeśli chcesz dodać nowe wartości do tej wartości domyślnej allowList, możesz wykonać następujące czynności:

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)

Jeśli chcesz ominąć nasz środek odkażający, ponieważ wolisz korzystać z dedykowanej biblioteki, na przykład DOMPurify , powinieneś wykonać następujące czynności:

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

Opcjonalnie za pomocą jQuery

Nie potrzebujesz jQuery w Bootstrap 5 , ale nadal możesz używać naszych komponentów z jQuery. Jeśli Bootstrap wykryje jQueryw windowobiekcie, doda wszystkie nasze komponenty do systemu wtyczek jQuery. Pozwala to na wykonanie następujących czynności:

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

To samo dotyczy innych naszych komponentów.

Brak konfliktu

Czasami konieczne jest użycie wtyczek Bootstrap z innymi frameworkami UI. W takich okolicznościach czasami mogą wystąpić kolizje przestrzeni nazw. Jeśli tak się stanie, możesz wywołać .noConflictwtyczkę, której wartość chcesz przywrócić.

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

Bootstrap oficjalnie nie obsługuje bibliotek JavaScript innych firm, takich jak Prototype lub jQuery UI. Pomimo .noConflictzdarzeń w przestrzeni nazw mogą występować problemy ze zgodnością, które trzeba naprawić samodzielnie.

Zdarzenia jQuery

Bootstrap wykryje jQuery, jeśli jQueryjest obecne w windowobiekcie i nie ma data-bs-no-jqueryustawionego atrybutu <body>. Jeśli zostanie znalezione jQuery, Bootstrap wyemituje zdarzenia dzięki systemowi zdarzeń jQuery. Więc jeśli chcesz słuchać zdarzeń Bootstrapa, będziesz musiał użyć metod jQuery ( .on, .one) zamiast addEventListener.

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

Wyłączony JavaScript

Wtyczki Bootstrap nie mają specjalnej funkcji awaryjnej, gdy JavaScript jest wyłączony. Jeśli zależy Ci na wrażeniach użytkownika w tym przypadku, użyj, <noscript>aby wyjaśnić sytuację (i jak ponownie włączyć JavaScript) użytkownikom i/lub dodaj własne niestandardowe rozwiązania zastępcze.