引入单个插件还是一次性引入所有插件

每个插件都可以单独的引入到页面中（注意插件间的依赖关系），或者一次性引入。bootstrap.js 和bootstrap.min.js 文件都将所有插件包含在一个文件中了（前者是未压缩版，后者是压缩版）。

Data 属性

你可以仅仅通过data属性API就能使用所有Bootstrap中的插件，而且不用写一行JavaScript代码。这是Bootstrap中的一等API，并且是你的首选方式。

特殊情况是，在某些情况下可能需要特意禁用这种默认动作。因此，我们特地提供了禁用data属性API的方式，通过解除绑定在body上的被命名为`'data-api'`的事件即可实现。如下所示：

$('body').off('.data-api')

还可以解除特定插件的事件绑定，只要将插件名和data-api链接在一起作为参数使用。如下所示：

$('body').off('.alert.data-api')

编程API

我们同时为所有Bootstrap插件提供了JavaScript API。所有公开的API都可以单独或链式调用，均返回其所操作的集合（和jQuery的API一致）。

$(".btn.danger").button("toggle").addClass("fat")

所有方法均可接受一个可选的参数对象、一个对此方法有特定意义的字符串或者什么也不传（即用默认参数初始化此插件）：

$("#myModal").modal()                       // initialized with defaults
$("#myModal").modal({ keyboard: false })   // initialized with no keyboard
$("#myModal").modal('show')                // initializes and invokes show immediately

每个插件都通过`Constructor` 属性暴露了其原始的构造函数：$.fn.popover.Constructor。如果你想获得某个特定插件的实例，可以直接从页面元素中获取：$('[rel=popover]').data('popover').

避免冲突

如果你需要将Bootstrap插件和其它UI框架一同使用。在这种情况下，随时都会导致命名空间冲突。如果这种情况发生了，你可以通过调用插件的 .noConflict 函数恢复其原始值。

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

事件

Bootstrap对多数插件的独有行为提供了自定义事件。 一般而言，这些事件都是以（英语）动词的原型和过去分词形式来表示的 - 动词原形形式的(例如： show) 在事件执行之前触发；过去分词形式的(例如：shown) 在动作执行完毕后触发。

所有动词原形形式的事件都提供了preventDefault函数。这能在动作执行之前使其停止。

$('#myModal').on('show', function (e) {
    if (!data) return e.preventDefault() // stops modal from being shown
})

关于过渡效果

对于简单的过度效果，只要在引入其它JS文件时一同引入bootstrap-transition.js文件即可。如果你引入的是编译（或压缩）之后的bootstrap.js文件，就不再需要引入此文件了，因为bootstrap.js文件已经包含了此插件。

使用案例

过渡效果插件的使用案例：

• 具有幻灯片或淡入效果的对话框
• 具有淡出效果的标签页
• 具有淡出效果的警告框
• 具有幻灯片效果的轮播板

案例

模态对话框是一类简洁、灵活的的弹框，他们具有精简的功能和友好的默认行为。

静态案例

带有标题、正文、页脚按钮的对话框。

<div class="modal hide fade">
  <div class="modal-header">
    <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
    <h3>对话框标题</h3>
  </div>
  <div class="modal-body">
    <p>One fine body…</p>
  </div>
  <div class="modal-footer">
    <a href="#" class="btn">关闭</a>
    <a href="#" class="btn btn-primary">Save changes</a>
  </div>
</div>

动态演示

点击下面的按钮会通过javascript触发一个模态对话框。对话框从页面顶端滑下的同时逐渐呈现。

<!-- Button to trigger modal -->
<a href="#myModal" role="button" class="btn" data-toggle="modal">查看演示案例</a>

<!-- Modal -->
<div id="myModal" class="modal hide fade" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
  <div class="modal-header">
    <button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button>
    <h3 id="myModalLabel">Modal header</h3>
  </div>
  <div class="modal-body">
    <p>One fine body…</p>
  </div>
  <div class="modal-footer">
    <button class="btn" data-dismiss="modal" aria-hidden="true">关闭</button>
    <button class="btn btn-primary">Save changes</button>
  </div>
</div>

调用方式

通过data属性

无需编写JavaScript代码即可生成一个对话框。在一个主控元素，例如按钮，上设置data-toggle="modal"，然后再设置data-target="#foo" 或href="#foo" 用以指向某个将要被启动的对话框。

<button type="button" data-toggle="modal" data-target="#myModal">Launch modal</button>

通过JavaScript

仅用一行JavaScript代码即可启动id为myModal的对话框：

$('#myModal').modal(options)

选项

上面的选项都可以通过data属性或JavaScript代码传递给组件。对于data属性，将选项名称附着于data-字符串之后，就像data-backdrop=""一样。

<a data-toggle="modal" href="remote.html" data-target="#modal">click me</a>

方法

.modal(options)

让你指定的内容变成一个模态对话框。接受一个可选的参数object.

$('#myModal').modal({
  keyboard: false
})

.modal('toggle')

手动打开或隐藏一个模态对话框。

$('#myModal').modal('toggle')

.modal('show')

手动打开一个模态对话框。

$('#myModal').modal('show')

.modal('hide')

手动隐藏一个模态对话框。

$('#myModal').modal('hide')

事件

Bootstrap中的模态对话框对外暴露了一些事件允许你监听。

$('#myModal').on('hidden', function () {
  // do something…
})

案例

通过此插件可以将下拉菜单加入到任何其他组件中，包括导航条、标签页。

导航条中的下拉菜单

标签页中的下拉菜单。

调用方式

通过data属性

在链接或按钮上添加data-toggle="dropdown"即可切换下拉菜单。

<div class="dropdown">
  <a class="dropdown-toggle" data-toggle="dropdown" href="#">Dropdown trigger</a>
  <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
    ...
  </ul>
</div>

为了保证URL符合规范，请使用data-target属性来代替href="#"。

<div class="dropdown">
  <a class="dropdown-toggle" id="dLabel" role="button" data-toggle="dropdown" data-target="#" href="/page.html">
    Dropdown
    <b class="caret"></b>
  </a>
  <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
    ...
  </ul>
</div>

通过JavaScript

通过JavaScript调用下拉菜单：

$('.dropdown-toggle').dropdown()

选项

无

方法

$().dropdown('toggle')

通过编程式api对某个特定的导航条或标签页导航切换下拉菜单。

用在导航条上

ScrollSpy插件根据滚动的位置自动更新导航条中相应的导航项。拖动下面区域的滚动条，使其低于导航条的位置，注意观察active类的变化。下拉菜单中的子项也会跟着变为高亮状态。

调用方式

通过data属性

只需将data-spy="scroll"添加到被监听的页面元素上（大部分情况是添加到body上），然后将data-target=".navbar"添加到导航部分，仅此而已，顶部导航条就拥有了监听滚动的功能。你可能希望将滚动监听应用到.nav组件上。

<body data-spy="scroll" data-target=".navbar">...</body>

通过JavaScript

通过JavaScript启动滚动监听：

$('#navbar').scrollspy()

方法

.scrollspy('refresh')

当滚动监听所作用的DOM有增删页面元素的操作时，需要调用下面的refresh方法：

$('[data-spy="scroll"]').each(function () {
  var $spy = $(this).scrollspy('refresh')
});

选项

所有参数都可以通过data属性或JavaScript传递。对于data属性，将参数名附着到data-后面，就像data-offset=""一样。

事件

案例

Add quick, dynamic tab functionality to transition through panes of local content, even via dropdown menus.

调用方式

通过JavaScript启动标签页（每个标签都需要被单独激活）：

$('#myTab a').click(function (e) {
  e.preventDefault();
  $(this).tab('show');
})

你可以通过多种方式激活标签页：

$('#myTab a[href="#profile"]').tab('show'); // Select tab by name
$('#myTab a:first').tab('show'); // Select first tab
$('#myTab a:last').tab('show'); // Select last tab
$('#myTab li:eq(2) a').tab('show'); // Select third tab (0-indexed)

标记

无需写任何JavaScript代码，只需简单的为页面元素指定data-toggle="tab" 或 data-toggle="pill"属性即可激活标签页或胶囊式标签页。为ul添加nav 和nav-tabs classe，即可为其添加Bootstrap的标签页样式。

<ul class="nav nav-tabs">
  <li><a href="#home" data-toggle="tab">首页</a></li>
  <li><a href="#profile" data-toggle="tab">Profile</a></li>
  <li><a href="#messages" data-toggle="tab">Messages</a></li>
  <li><a href="#settings" data-toggle="tab">Settings</a></li>
</ul>

方法

$().tab

激活某个标签页和对应的内容容器。应当为标签页指定data-target 或 href用以标记DOM树中的目标容器节点。

<ul class="nav nav-tabs" id="myTab">
  <li class="active"><a href="#home">首页</a></li>
  <li><a href="#profile">Profile</a></li>
  <li><a href="#messages">Messages</a></li>
  <li><a href="#settings">Settings</a></li>
</ul>

<div class="tab-content">
  <div class="tab-pane active" id="home">...</div>
  <div class="tab-pane" id="profile">...</div>
  <div class="tab-pane" id="messages">...</div>
  <div class="tab-pane" id="settings">...</div>
</div>

<script>
  $(function () {
    $('#myTab a:last').tab('show');
  })
</script>

事件

$('a[data-toggle="tab"]').on('shown', function (e) {
  e.target // activated tab
  e.relatedTarget // previous tab
})

案例

本插件受到Jason Frame开发的jQuery.tipsy插件的启发。Tooltips做了很多改进，例如不需要依赖图片，而是改用CSS3实现动画效果，用data属性存储标题信息。

出于性能方面的考虑，工具提示和弹出提示的data属性API是选择性加入的，也即是说你必要自己初始化他们。

将鼠标停悬在下面的链接上查看工具提示：

四个方向

输入框组中的工具提示

将工具提示和弹出提示与Bootstrap中的输入框组一同使用时，为了避免不必要的影响，你需要设置container（文档如下）：

调用方式

通过JavaScript触发工具提示：

$('#example').tooltip(options)

选项

可以通过data属性或JavaScript传递参数。对于data属性，将参数名附着到data-后面即可，例如, data-animation=""。

标记

<a href="#" data-toggle="tooltip" title="first tooltip">hover over me</a>

方法

$().tooltip(options)

对一组页面元素绑定一个工具提示处理器。

.tooltip('show')

弹出某个页面元素的工具提示。

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

.tooltip('hide')

隐藏某个页面元素的工具提示。

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

.tooltip('toggle')

打开或隐藏某个页面元素的工具提示。

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

.tooltip('destroy')

隐藏并销毁某个页面元素的工具提示。

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

案例

对任意页面元素添加一个覆盖层展示额外信息，就行iPad中的类似功能。将鼠标悬停在下面的按钮上即可触发一个弹出提示。必须先引入 工具提示 插件

静态弹出提示

有4个可选参数：top、right、bottom和left 对其方式。

No markup shown as popovers are generated from JavaScript and content within a data attribute.

动态演示

Four directions

调用方式

通过JavaScript启用弹出提示：

$('#example').popover(options)

选项

可以通过data属性或JavaScript传递参数。对于data属性，将参数名附着到data-之后，例如data-animation=""。

标记

For performance reasons, the Tooltip and Popover data-apis are opt in. If you would like to use them just specify a selector option.

方法

$().popover(options)

对一组页面元素初始化弹出提示。

.popover('show')

打开某个页面元素的弹出提示。

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

.popover('hide')

隐藏某个页面元素的弹出提示。

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

.popover('toggle')

打开或隐藏某个页面元素的弹出提示。

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

.popover('destroy')

隐藏并销毁某个页面元素的弹出提示。

$('#element').popover('destroy')

警告框案例

利用此插件对所有警告消息添加取消功能。

调用方式

通过JavaScript为某个警告框添加取消功能：

$(".alert").alert()

标记

仅需将data-dismiss="alert"添加到关闭按钮即可自动赋予某个警告框关闭的功能。

<a class="close" data-dismiss="alert" href="#">&times;</a>

方法

$().alert()

赋予所有警告框以关闭功能。如果你希望警告框在关闭时带有动画效果，请确保.fade 和.in类已经应用到这些警告框上了。

.alert('close')

关闭某个警告框。

$(".alert").alert('close')

事件

Bootstrap中的警告框对外暴露了一些事件允许你监听。

$('#my-alert').bind('closed', function () {
  // do something…
})

使用案例

按钮可以实现很多功能。为工具条（toolbar）之类的组件赋予控制按钮的状态或者创建一组按钮的功能。

状态

添加data-loading-text="正在加载"可以为按钮设置正在加载状态。

<button type="button" class="btn btn-primary" data-loading-text="Loading...">Loading state</button>

选中

添加data-toggle="button"可以激活单个按钮的选中状态。

<button type="button" class="btn btn-primary" data-toggle="button">Single Toggle</button>

复选

添加data-toggle="buttons-checkbox"可以为按钮组添加复选框样式的勾选风格。

<div class="btn-group" data-toggle="buttons-checkbox">
  <button type="button" class="btn btn-primary">Left</button>
  <button type="button" class="btn btn-primary">Middle</button>
  <button type="button" class="btn btn-primary">Right</button>
</div>

单选

添加data-toggle="buttons-radio"为按钮组添加单选框样式的选中风格。

<div class="btn-group" data-toggle="buttons-radio">
  <button type="button" class="btn btn-primary">Left</button>
  <button type="button" class="btn btn-primary">Middle</button>
  <button type="button" class="btn btn-primary">Right</button>
</div>

调用方式

通过JavaScript激活按钮：

$('.nav-tabs').button()

标记

按钮插件的Data属性是完整的。通过下面的案例可以看到各种类型的标记。

选项

无

方法

$().button('toggle')

Toggles push state. Gives the button the appearance that it has been activated.

<button type="button" class="btn" data-toggle="button" >…</button>

$().button('loading')

Sets button state to loading - disables button and swaps text to loading text. Loading text should be defined on the button element using the data attribute data-loading-text.

<button type="button" class="btn" data-loading-text="loading stuff..." >...</button>

$().button('reset')

Resets button state - swaps text to original text.

$().button(string)

Resets button state - swaps text to any data defined text state.

<button type="button" class="btn" data-complete-text="finished!" >...</button>
<script>
  $('.btn').button('complete')
</script>

关于

给可折叠的组件，如手风琴式的切换和导航，提供基本和灵活的样式。

* 需要包含过渡效果插件。

案例

通过折叠插件，我们可以创建一个简单的手风琴式的组件：

<div class="accordion" id="accordion2">
  <div class="accordion-group">
    <div class="accordion-heading">
      <a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion2" href="#collapseOne">
        Collapsible Group Item #1
      </a>
    </div>
    <div id="collapseOne" class="accordion-body collapse in">
      <div class="accordion-inner">
        Anim pariatur cliche...
      </div>
    </div>
  </div>
  <div class="accordion-group">
    <div class="accordion-heading">
      <a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion2" href="#collapseTwo">
        Collapsible Group Item #2
      </a>
    </div>
    <div id="collapseTwo" class="accordion-body collapse">
      <div class="accordion-inner">
        Anim pariatur cliche...
      </div>
    </div>
  </div>
</div>
...

使用此插件时可以无需写任何标记。让按钮控制另一个元素进行展开和折叠。

<button type="button" class="btn btn-danger" data-toggle="collapse" data-target="#demo">
  simple collapsible
</button>

<div id="demo" class="collapse in"> … </div>

调用方式

通过data属性

Just add data-toggle="collapse" and a data-target to element to automatically assign control of a collapsible element. The data-target attribute accepts a css selector to apply the collapse to. Be sure to add the class collapse to the collapsible element. If you'd like it to default open, add the additional class in.

To add accordion-like group management to a collapsible control, add the data attribute data-parent="#selector". Refer to the demo to see this in action.

通过JavaScript

手动调用：

$(".collapse").collapse()

选项

项的传递可通过data属性或JavaScript。对于data属性，需要附加选项名称data-，例如data-parent=""。

方法

.collapse(options)

Activates your content as a collapsible element. Accepts an optional options object.

$('#myCollapsible').collapse({
  toggle: false
})

.collapse('toggle')

Toggles a collapsible element to shown or hidden.

.collapse('show')

Shows a collapsible element.

.collapse('hide')

Hides a collapsible element.

事件

Bootstrap's collapse class exposes a few events for hooking into collapse functionality.

$('#myCollapsible').on('hidden', function () {
  // do something…
})

轮播案例

下面就是一个轮播组件的案例。

First Thumbnail label

Cras justo odio, dapibus ac facilisis in, egestas eget quam. Donec id elit non mi porta gravida at eget metus. Nullam id dolor id nibh ultricies vehicula ut id elit.

Second Thumbnail label

Cras justo odio, dapibus ac facilisis in, egestas eget quam. Donec id elit non mi porta gravida at eget metus. Nullam id dolor id nibh ultricies vehicula ut id elit.

Third Thumbnail label

Cras justo odio, dapibus ac facilisis in, egestas eget quam. Donec id elit non mi porta gravida at eget metus. Nullam id dolor id nibh ultricies vehicula ut id elit.

‹ ›

<div id="myCarousel" class="carousel slide">
  <ol class="carousel-indicators">
    <li data-target="#myCarousel" data-slide-to="0" class="active"></li>
    <li data-target="#myCarousel" data-slide-to="1"></li>
    <li data-target="#myCarousel" data-slide-to="2"></li>
  </ol>
  <!-- Carousel items -->
  <div class="carousel-inner">
    <div class="active item">…</div>
    <div class="item">…</div>
    <div class="item">…</div>
  </div>
  <!-- Carousel nav -->
  <a class="carousel-control left" href="#myCarousel" data-slide="prev">&lsaquo;</a>
  <a class="carousel-control right" href="#myCarousel" data-slide="next">&rsaquo;</a>
</div>

调用方式

通过data属性

使用data属性可以很容易的控制轮播的位置。data-slide内可以包含prev 或 next，他们可以改变当前帧。另外，使用data-slide-to可以传递某个帧的下标，例如data-slide-to="2"，这样就可以直接跳转到这个指定的帧 -- 下标从0开始计算。

通过JavaScript

手工启动轮播：

$('.carousel').carousel()

选项

参数可以通过data属性或JavaScript传递。对于data属性，将参数名称附着到data-之后，例如data-interval=""。

方法

.carousel(options)

初始化一个带有可选参数object的轮播，并且自动开始循环播放。

$('.carousel').carousel({
  interval: 2000
})

.carousel('cycle')

从左向右循环播放。

.carousel('pause')

停止循环播放。

.carousel(number)

循环到指定帧（下标从0开始，类似数组）。

.carousel('prev')

返回到上一帧。

.carousel('next')

下一帧。

事件

Bootstrap的轮播插件对外暴露了两个可被监听的事件。

案例

简单，易于扩展，可迅速地为表单中的文本输入框创建优雅的输入提示。

<input type="text" data-provide="typeahead">

需要设置autocomplete="off"以阻止浏览器的默认提示菜单遮盖Bootstrap的输入提示下拉菜单。

调用方式

通过data属性

通过添加data属性给页面元素注册输入提示功能，就像上面的案例一样。

通过JavaScript

手动调用输入提示：

$('.typeahead').typeahead()

选项

可以通过data属性或JavaScript传递参数。对于data属性，将参数名附着到data-之后，例如data-source=""。

方法

.typeahead(options)

为输入框初始化输入提示功能。

案例

本页面左侧就是一个附加导航的实际案例。

调用方式

通过data属性

只需添加data-spy="affix"到任意需要监听的页面元素上，就可以很容易的将其变为附加导航。然后使用偏移量来控制其位置。

<div data-spy="affix" data-offset-top="200">...</div>

通过JavaScript

通过JavaScript启动：

$('#navbar').affix()

选项

选项的传递可通过数据属性或JavaScript. 对于数据属性, 需要附加选项名称 data-，例如data-offset-top="200"。