JavaScript

İsteğe bağlı JavaScript eklentilerimizle Bootstrap'a hayat verin. Her bir eklenti, verilerimiz ve programatik API seçeneklerimiz ve daha fazlası hakkında bilgi edinin.

Bu sayfada

Bireysel veya derlenmiş

Eklentiler tek tek dahil edilebilir (Bootstrap'in bireyi kullanılarak js/dist/*.js) veya tümü aynı anda bootstrap.jsveya küçültülmüş olarak bootstrap.min.js(her ikisini birden dahil etmeyin) dahil edilebilir.

/js/dist/*.jsBir paketleyici (Webpack, Parsel, Vite…) kullanıyorsanız, UMD'ye hazır dosyaları kullanabilirsiniz .

JavaScript çerçeveleriyle kullanım

Bootstrap CSS herhangi bir çerçeve ile kullanılabilirken , Bootstrap JavaScript, DOM hakkında tam bilgi sahibi olduğunu varsayan React, Vue ve Angular gibi JavaScript çerçeveleriyle tam uyumlu değildir . Hem Bootstrap hem de çerçeve aynı DOM öğesini mutasyona uğratmaya çalışabilir ve bu da "açık" konumda takılı kalan açılır listeler gibi hatalara neden olabilir.

Bu tür çerçeveleri kullananlar için daha iyi bir alternatif , Bootstrap JavaScript yerine çerçeveye özel bir paket kullanmaktır. İşte en popüler seçeneklerden bazıları:

React: React Bootstrap
Vue: BootstrapVue (şu anda yalnızca Vue 2 ve Bootstrap 4'ü destekler)
Açısal: ng-önyükleme

Bootstrap'i modül olarak kullanma

Kendin dene! Bootstrap'i ES modülü olarak kullanmak için kaynak kodunu ve çalışma demosunu twbs/examples deposundan indirin . Örneği StackBlitz'de de açabilirsiniz .

Hedeflenen tarayıcılarınız destekliyorsa , Bootstrap'i tarayıcıda bir modül olarak kullanmanıza izin veren ESM( bootstrap.esm.jsve ) olarak oluşturulmuş bir Bootstrap sürümü sunuyoruz .bootstrap.esm.min.js

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

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

JS paketleyicileriyle karşılaştırıldığında, tarayıcıda ESM kullanmak, modül adı yerine tam yolu ve dosya adını kullanmanızı gerektirir. Tarayıcıda JS modülleri hakkında daha fazla bilgi edinin. Bu yüzden yukarıdaki 'bootstrap.esm.min.js'yerine kullanıyoruz. 'bootstrap'Bununla birlikte, Popper'ı JavaScript'imize şu şekilde içe aktaran Popper bağımlılığımız nedeniyle bu daha da karmaşık hale gelir:

import * as Popper from "@popperjs/core"

Bunu olduğu gibi denerseniz, konsolda aşağıdakine benzer bir hata görürsünüz:

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

Bunu düzeltmek için, importmapyolları tamamlamak için isteğe bağlı modül adlarını çözmek için an kullanabilirsiniz. Hedeflenen tarayıcılarınız desteklemiyorsa , es-module-shims projesini importmapkullanmanız gerekecektir . Bootstrap ve Popper için şu şekilde çalışır:

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

bağımlılıklar

Bazı eklentiler ve CSS bileşenleri diğer eklentilere bağlıdır. Eklentileri tek tek eklerseniz, bu bağımlılıkları belgelerde kontrol ettiğinizden emin olun.

Açılır listelerimiz, açılır pencerelerimiz ve araç ipuçlarımız da Popper'a bağlıdır .

Veri öznitelikleri

Hemen hemen tüm Bootstrap eklentileri, veri öznitelikleri ile yalnızca HTML aracılığıyla etkinleştirilebilir ve yapılandırılabilir (tercih ettiğimiz JavaScript işlevselliğini kullanma yöntemimiz). Tek bir öğe üzerinde yalnızca bir veri özniteliği kümesi kullandığınızdan emin olun (örneğin, aynı düğmeden bir araç ipucunu ve modu tetikleyemezsiniz.)

Seçenekler veri öznitelikleri veya JavaScript aracılığıyla iletilebildiğinden data-bs-, örneğinde olduğu gibi öğesine bir seçenek adı ekleyebilirsiniz data-bs-animation="{value}". Seçenekleri veri öznitelikleri üzerinden geçirirken , seçenek adının “ camelCase ” yerine “ kebab-case ” olarak değiştirildiğinden emin olun. Örneğin, data-bs-custom-class="beautifier"yerine kullanın data-bs-customClass="beautifier".

Bootstrap 5.2.0'dan itibaren, tüm bileşenler , bir JSON dizesi olarak basit bileşen yapılandırmasını barındırabilen deneysel bir ayrılmış veri özniteliğini destekler. data-bs-configBir öğe data-bs-config='{"delay":0, "title":123}'ve data-bs-title="456"özniteliklere sahip olduğunda, nihai titledeğer olacak 456ve ayrı veri öznitelikleri üzerinde verilen değerleri geçersiz kılacaktır data-bs-config. Ek olarak, mevcut veri öznitelikleri, gibi JSON değerlerini barındırabilir data-bs-delay='{"show":0,"hide":150}'.

seçiciler

Performans nedenleriyle DOM öğelerini sorgulamak için yerel querySelectorve yöntemlerini kullanıyoruz, bu nedenle geçerli seçiciler kullanmanız gerekir . gibi özel seçiciler kullanıyorsanız , bunlardan kaçındığınızdan emin olun.querySelectorAllcollapse:Example

Olaylar

Bootstrap, çoğu eklentinin benzersiz eylemleri için özel etkinlikler sağlar. Genellikle bunlar mastar ve geçmiş ortaç biçiminde gelir - burada mastar (örn. show) bir olayın başlangıcında tetiklenir ve geçmiş ortaç biçimi (örn. shown) bir eylemin tamamlanmasıyla tetiklenir.

Tüm mastar olaylar preventDefault()işlevsellik sağlar. Bu, bir eylemin yürütülmesini başlamadan önce durdurma yeteneği sağlar. Bir olay işleyicisinden false döndürmek de otomatik olarak preventDefault().

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

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

Programatik API

Tüm yapıcılar isteğe bağlı bir seçenekler nesnesini kabul eder veya hiçbir şey kabul etmez (bu, bir eklentiyi varsayılan davranışıyla başlatır):

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

Belirli bir eklenti örneği almak istiyorsanız, her eklenti bir getInstanceyöntem sunar. Örneğin, bir örneği doğrudan bir öğeden almak için:

bootstrap.Popover.getInstance(myPopoverEl)

Bu yöntem null, istenen öğe üzerinden bir örnek başlatılmazsa geri döner.

Alternatif olarak, getOrCreateInstancebir DOM öğesiyle ilişkili örneği almak veya başlatılmamış olması durumunda yeni bir tane oluşturmak için kullanılabilir.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Bir örneğin başlatılmamış olması durumunda, ikinci argüman olarak isteğe bağlı bir yapılandırma nesnesini kabul edebilir ve kullanabilir.

Yapıcılarda CSS seçicileri

getInstanceve yöntemlerine ek olarak , tüm eklenti oluşturucuları ilk argüman olarak getOrCreateInstancebir DOM öğesini veya geçerli bir CSS seçicisini kabul edebilir. querySelectorEklentilerimiz yalnızca tek bir öğeyi desteklediğinden , bu yöntemle eklenti öğeleri bulunur .

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

Asenkron fonksiyonlar ve geçişler

Tüm programatik API yöntemleri zaman uyumsuzdur ve geçiş başlatıldığında, ancak bitmeden önce arayana geri döner . Geçiş tamamlandıktan sonra bir eylemi gerçekleştirmek için ilgili olayı dinleyebilirsiniz.

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

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

Ek olarak, geçiş yapan bir bileşen üzerindeki bir yöntem çağrısı yoksayılacaktır .

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`yöntem

disposeYöntemi hemen sonrasında kullanmak doğru gibi görünse hide()de yanlış sonuçlara yol açacaktır. İşte problem kullanımına bir örnek:

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

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

Varsayılan ayarları

Eklentinin Constructor.Defaultnesnesini değiştirerek bir eklentinin varsayılan ayarlarını değiştirebilirsiniz:

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

Yöntemler ve özellikler

Her Bootstrap eklentisi, aşağıdaki yöntemleri ve statik özellikleri ortaya çıkarır.

Yöntem	Tanım
`dispose`	Bir elemanın kipini yok eder. (DOM öğesinde depolanan verileri kaldırır)
`getInstance`	Bir DOM öğesiyle ilişkili mod örneğini almanızı sağlayan statik yöntem.
`getOrCreateInstance`	Bir DOM öğesiyle ilişkili mod örneğini almanıza veya başlatılmamış olması durumunda yeni bir tane oluşturmanıza izin veren statik yöntem.

statik özellik	Tanım
`NAME`	Eklenti adını döndürür. (Örnek: `bootstrap.Tooltip.NAME`)
`VERSION`	`VERSION`Bootstrap eklentilerinin her birinin sürümüne , eklentinin kurucusunun özelliği aracılığıyla erişilebilir (Örnek: `bootstrap.Tooltip.VERSION`)

dezenfektan

Araç ipuçları ve Popover'lar, HTML'yi kabul eden seçenekleri sterilize etmek için yerleşik dezenfektanımızı kullanır.

Varsayılan allowListdeğer aşağıdaki gibidir:

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

Bu varsayılana yeni değerler eklemek allowLististiyorsanız aşağıdakileri yapabilirsiniz:

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 gibi özel bir kitaplık kullanmayı tercih ettiğiniz için dezenfektanımızı atlamak istiyorsanız , aşağıdakileri yapmalısınız:

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

İsteğe bağlı olarak jQuery kullanarak

Bootstrap 5'te jQuery'ye ihtiyacınız yok , ancak bileşenlerimizi jQuery ile kullanmak hala mümkün. Bootstrap nesnede algılarsa jQuery, windowtüm bileşenlerimizi jQuery'nin eklenti sistemine ekler. Bu, aşağıdakileri yapmanızı sağlar:

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

Aynı şey diğer bileşenlerimiz için de geçerli.

Çatışma yok

Bazen Bootstrap eklentilerini diğer UI çerçeveleriyle birlikte kullanmak gerekir. Bu durumlarda, zaman zaman ad alanı çakışmaları meydana gelebilir. Böyle bir durumda, .noConflictdeğerini geri almak istediğiniz eklentiyi arayabilirsiniz.

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

Bootstrap, Prototype veya jQuery UI gibi üçüncü taraf JavaScript kitaplıklarını resmi olarak desteklemez. Ad alanlı olaylara rağmen .noConflict, kendi başınıza düzeltmeniz gereken uyumluluk sorunları olabilir.

jQuery olayları

jQueryBootstrap , windownesnede varsa ve data-bs-no-jqueryüzerinde ayarlanmış bir öznitelik yoksa jQuery'yi algılar <body>. jQuery bulunursa, Bootstrap, jQuery'nin olay sistemi sayesinde olayları yayacaktır. Yani Bootstrap olaylarını dinlemek istiyorsanız, jQuery yöntemlerini ( .on, .one) kullanmak zorunda kalacaksınız addEventListener.

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

Devre Dışı JavaScript

JavaScript devre dışı bırakıldığında Bootstrap eklentilerinin özel bir geri dönüşü yoktur. Bu durumda kullanıcı deneyimini önemsiyorsanız <noscript>, durumu (ve JavaScript'in nasıl yeniden etkinleştirileceğini) kullanıcılarınıza açıklamak ve/veya kendi özel yedeklerinizi eklemek için kullanın.