Bootstrap JavaScript插件 - Bootstrap中文网

单个还是全部引入

插件可以单个引入（使用Bootstrap提供的单个*.js文件），或一次性全部引入（使用bootstrap.js或压缩版的bootstrap.min.js）。

不要将两份文件全部引入

bootstrap.js和bootstrap.min.js同样是包含了所有插件。区别是：一个没有压缩，一个进行了压缩。

插件之间的依赖

某些插件和CSS组件依赖于其它插件。如果你是单个引入每个插件的，请确保在文档中检查插件之间的依赖关系。注意，所有插件都依赖jQuery（也就是说，jQuery必须在所有插件之前引入页面）。 bower.json文件中列出了所支持的jQuery版本。

Data属性

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

话又说回来，在某些情况下可能需要将此功能关闭。因此，我们还提供了关闭data属性API的方式，即解除绑定到文档命名空间上的所有事件data-api。就像下面这样：

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

另外，如果是针对某个特定的插件，只需在data-api前面添加那个插件的名称作为命名空间，如下：

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

编程式API

我们还提供了所有Bootstrap插件的纯JavaScript API。所有公开的API都是支持单独或链式调用的，并且返回其所操作的元素集合（注：和jQuery的调用形式一致）。

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

所有方法都可以接受一个可选的option对象作为参数，或者一个代表特定方法的字符串，或者什么也不提供（在这种情况下，插件将会以默认值初始化）：

$('#myModal').modal()                      // 使用默认值初始化
$('#myModal').modal({ keyboard: false })   // 初始化。不支持键盘导航
$('#myModal').modal('show')                // 初始化并立即展示</p>

每个插件还通过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为大部分插件所具有的动作提供了自定义事件。一般来说，这些事件都有不定式和过去式两种动词形式，例如，不定式形式的动词（例如shown）表示其在事件开始时被触发；而过去式动词（例如shown）表示其在动作直接完毕之后被触发。

从3.0.0开始，所有的Bootstrap事件都采用了命名空间。

所有以不定式形式的动词命名的事件都提供了preventDefault功能。这就赋予你在动作开始执行前将其停止的能力。

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

第三方工具库

Bootstrap官方不提供对第三方JavaScript工具库的支持，例如Prototype或jQuery UI。除了.noConflict和采用命名空间的事件，还可能会有兼容性方面的问题，这就需要你自己来处理了。你可以在此邮件列表获取帮助。

关于过渡效果

对于简单的过渡效果，只需将transition.js和其它JS文件一起引入即可。如果你使用的是编译（或压缩）好的bootstrap.js文件，就无需再单独将其引入了。

What's inside

Transition.js是针对 transitionEnd事件的一个基本助手工具，也是对CSS过渡效果的模拟。它被其它插件用来检测当前浏览器对CSS过渡效果是否支持。

案例

模态框经过了优化，更加灵活，以弹出对话框的形式出现，具有最小和最实用的功能集。

不支持模态框重叠

千万不要在一个模态框上重叠另一个模态框。要想同时支持多个模态框，需要自己写额外的代码来实现。

对于移动设备的附加说明

本文档针对移动设备上使用模态框有一些附加说明。请参考浏览器支持章节。

静态案例

以下模态框包含了模态框的头、体和一组在放置于底部的按钮。

<div class="modal fade">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
        <h4 class="modal-title">Modal title</h4>
      </div>
      <div class="modal-body">
        <p>One fine body&hellip;</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div><!-- /.modal-content -->
  </div><!-- /.modal-dialog -->
</div><!-- /.modal -->

动态演示

点击下面的按钮即可通过JavaScript启动一个模态框。此模态框将从上到下、逐渐浮现到页面前。

  <!-- Button trigger modal -->
<button class="btn btn-primary btn-lg" data-toggle="modal" data-target="#myModal">
  Launch demo modal
</button>

<!-- Modal -->
<div class="modal fade" id="myModal" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
        <h4 class="modal-title" id="myModalLabel">Modal title</h4>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div><!-- /.modal-content -->
  </div><!-- /.modal-dialog -->
</div><!-- /.modal -->

增强模态框的可访问性

请确保为.modal添加了role="dialog"；aria-labelledby="myModalLabel"属性指向模态框标题；aria-hidden="true"告诉辅助性工具略过模态框的DOM元素。

另外，你还应该为模态框添加描述性信息。为.modal添加aria-describedby属性用以指向描述信息。

用法

The modal plugin toggles your hidden content on demand, via data attributes or JavaScript. It also adds .model-open to the <body> to override default scrolling behavior and generates a .modal-backdrop to provide a click area for dismissing shown modals when clicking outside the modal.

通过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=""。

名称	类型	默认值	描述
backdrop	boolean or the string `'static'`	true	Includes a modal-backdrop element. Alternatively, specify `static` for a backdrop which doesn't close the modal on click.
keyboard	boolean	true	Closes the modal when escape key is pressed
show	boolean	true	Shows the modal when initialized.
remote	path	false	If a remote URL is provided, content will be loaded via jQuery's `load` method and injected into the root of the modal element. If you're using the data-api, you may alternatively use the `href` attribute to specify the remote source. An example of this is shown below: `<a data-toggle="modal" href="remote.html" data-target="#modal">Click me</a>`

方法

.modal(options)

将你指定的内容作为模态框启动。其接受一个可选的object类型的参数。

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

.modal('toggle')

手动启动或隐藏模态框。在模态框真正显示或隐藏前返回到调用函数 (i.e. 在 shown.bs.modal 或 hidden.bs.modal 事件发生之前)。

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

.modal('show')

手动打开一个模态框。在模态框真正显示或隐藏前返回到调用函数 (i.e. 在 shown.bs.modal 事件发生之前)。

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

.modal('hide')

手动隐藏一个模态框。在模态框真正显示或隐藏前返回到调用函数 (i.e. 在 hidden.bs.modal 事件发生之前)。

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

事件

Bootstrap的模态框类暴露了一些事件用于截获并执行自己的代码。

事件类型	描述
show.bs.modal	This event fires immediately when the `show` instance method is called. If caused by a click, the clicked element is available as the `relatedTarget` property of the event.
shown.bs.modal	This event is fired when the modal has been made visible to the user (will wait for CSS transitions to complete). If caused by a click, the clicked element is available as the `relatedTarget` property of the event.
hide.bs.modal	This event is fired immediately when the `hide` instance method has been called.
hidden.bs.modal	This event is fired when the modal has finished being hidden from the user (will wait for CSS transitions to complete).

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

案例

通过此插件可以为几乎所有东西添加下拉菜单，包括导航条、标签页、胶囊式按钮。

用于导航条

用于标签页

用法

Via data attributes or JavaScript, the dropdown plugin toggles hidden content (dropdown menus) by toggling the .open class on the parent list item. When opened, the plugin also adds .dropdown-backdrop as a click area for closing dropdown menus when clicking outside the menu.

通过data属性

通过向链接或按钮添加data-toggle="dropdown"可以打开或关闭下拉菜单。

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

To keep URLs intact, use the data-target attribute instead of href="#".

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


  <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
    ...
  </ul>
</div>

通过JavaScript

通过JavaScript打开或关闭下拉菜单：

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

选项

None

方法

$().dropdown('toggle')

为导航条或标签页式导航打开或关闭下拉菜单。

事件

事件类型	描述
show.bs.dropdown	This event fires immediately when the show instance method is called.
shown.bs.dropdown	This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete).
hide.bs.dropdown	This event is fired immediately when the hide instance method has been called.
hidden.bs.dropdown	This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete).

$('#myDropdown').on('show.bs.dropdown', function () {
  // do something…
})

案例

滚动监听插件可以根据滚动条的位置自动更新所对应的导航标记。你可以试试滚动这个页面，看看左侧导航的变化。

@fat

Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.

@mdo

Veniam marfa mustache skateboard, adipisicing fugiat velit pitchfork beard. Freegan beard aliqua cupidatat mcsweeney's vero. Cupidatat four loko nisi, ea helvetica nulla carles. Tattooed cosby sweater food truck, mcsweeney's quis non freegan vinyl. Lo-fi wes anderson +1 sartorial. Carles non aesthetic exercitation quis gentrify. Brooklyn adipisicing craft beer vice keytar deserunt.

one

Occaecat commodo aliqua delectus. Fap craft beer deserunt skateboard ea. Lomo bicycle rights adipisicing banh mi, velit ea sunt next level locavore single-origin coffee in magna veniam. High life id vinyl, echo park consequat quis aliquip banh mi pitchfork. Vero VHS est adipisicing. Consectetur nisi DIY minim messenger bag. Cred ex in, sustainable delectus consectetur fanny pack iphone.

two

In incididunt echo park, officia deserunt mcsweeney's proident master cleanse thundercats sapiente veniam. Excepteur VHS elit, proident shoreditch +1 biodiesel laborum craft beer. Single-origin coffee wayfarers irure four loko, cupidatat terry richardson master cleanse. Assumenda you probably haven't heard of them art party fanny pack, tattooed nulla cardigan tempor ad. Proident wolf nesciunt sartorial keffiyeh eu banh mi sustainable. Elit wolf voluptate, lo-fi ea portland before they sold out four loko. Locavore enim nostrud mlkshk brooklyn nesciunt.

three

Ad leggings keytar, brunch id art party dolor labore. Pitchfork yr enim lo-fi before they sold out qui. Tumblr farm-to-table bicycle rights whatever. Anim keffiyeh carles cardigan. Velit seitan mcsweeney's photo booth 3 wolf moon irure. Cosby sweater lomo jean shorts, williamsburg hoodie minim qui you probably haven't heard of them et cardigan trust fund culpa biodiesel wes anderson aesthetic. Nihil tattooed accusamus, cred irony biodiesel keffiyeh artisan ullamco consequat.

Keytar twee blog, culpa messenger bag marfa whatever delectus food truck. Sapiente synth id assumenda. Locavore sed helvetica cliche irony, thundercats you probably haven't heard of them consequat hoodie gluten-free lo-fi fap aliquip. Labore elit placeat before they sold out, terry richardson proident brunch nesciunt quis cosby sweater pariatur keffiyeh ut helvetica artisan. Cardigan craft beer seitan readymade velit. VHS chambray laboris tempor veniam. Anim mollit minim commodo ullamco thundercats.

用法

通过data属性

通过为需要监听的页面元素（一般是<body>）添加data-spy="scroll"就可很轻松的为顶部导航条添加滚动监听功能。然后为其添加data-target属性，此属性的值为任何Bootstrap中.nav组件的父元素的ID或class。

<body data-spy="scroll" data-target=".navbar-example">
  ...
  <div class="navbar-example">
    <ul class="nav nav-tabs">
      ...
    </ul>
  </div>
  ...
</body>

通过JavaScript

通过JavaScript启动滚动监听：

$('body').scrollspy({ target: '.navbar-example' })

导航链接地址必须有对应的目标

导航条内的链接地址必须有对应的页面元素具有同样的ID值。例如，<a href="#home">home</a>必须对应DOM中例如<div id="home"></div>。

方法

.scrollspy('refresh')

使用滚动监听插件时，每当页面中从DOM中增加或删除页面元素时，都需要调用此方法以，如下：

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

选项

可以将选项通过data属性或JavaScript传递。对于data属性，需要将选项名称放到data-之后，例如data-offset=""。

名称	类型	默认值	描述
offset	number	10	Pixels to offset from top when calculating position of scroll.

事件

事件类型	描述
activate.bs.scrollspy	当滚动监听插件将某个元素置为active时，此事件被触发。

$('#myScrollspy').on('activate.bs.scrollspy', function () {
  // do something…
})

案例

通过添加标签页功能，可以让多个内容区域快速、动态切换。下拉菜单也可以使用。

Raw denim you probably haven't heard of them jean shorts Austin. Nesciunt tofu stumptown aliqua, retro synth master cleanse. Mustache cliche tempor, williamsburg carles vegan helvetica. Reprehenderit butcher retro keffiyeh dreamcatcher synth. Cosby sweater eu banh mi, qui irure terry richardson ex squid. Aliquip placeat salvia cillum iphone. Seitan aliquip quis cardigan american apparel, butcher voluptate nisi qui.

Food truck fixie locavore, accusamus mcsweeney's marfa nulla single-origin coffee squid. Exercitation +1 labore velit, blog sartorial PBR leggings next level wes anderson artisan four loko farm-to-table craft beer twee. Qui photo booth letterpress, commodo enim craft beer mlkshk aliquip jean shorts ullamco ad vinyl cillum PBR. Homo nostrud organic, assumenda labore aesthetic magna delectus mollit. Keytar helvetica VHS salvia yr, vero magna velit sapiente labore stumptown. Vegan fanny pack odio cillum wes anderson 8-bit, sustainable jean shorts beard ut DIY ethical culpa terry richardson biodiesel. Art party scenester stumptown, tumblr butcher vero sint qui sapiente accusamus tattooed echo park.

Etsy mixtape wayfarers, ethical wes anderson tofu before they sold out mcsweeney's organic lomo retro fanny pack lo-fi farm-to-table readymade. Messenger bag gentrify pitchfork tattooed craft beer, iphone skateboard locavore carles etsy salvia banksy hoodie helvetica. DIY synth PBR banksy irony. Leggings gentrify squid 8-bit cred pitchfork. Williamsburg banh mi whatever gluten-free, carles pitchfork biodiesel fixie etsy retro mlkshk vice blog. Scenester cred you probably haven't heard of them, vinyl craft beer blog stumptown. Pitchfork sustainable tofu synth chambray yr.

Trust fund seitan letterpress, keytar raw denim keffiyeh etsy art party before they sold out master cleanse gluten-free squid scenester freegan cosby sweater. Fanny pack portland seitan DIY, art party locavore wolf cliche high life echo park Austin. Cred vinyl keffiyeh DIY salvia PBR, banh mi before they sold out farm-to-table VHS viral locavore cosby sweater. Lomo wolf viral, mustache readymade thundercats keffiyeh craft beer marfa ethical. Wolf salvia freegan, sartorial keffiyeh echo park vegan.

扩展了标签页式导航

此插件为标签页式导航组件添加了标签页内容区。

用法

通过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)

标记

You can activate a tab or pill navigation without writing any JavaScript by simply specifying data-toggle="tab" or data-toggle="pill" on an element. Adding the nav and nav-tabs classes to the tab ul will apply the Bootstrap tab styling, while adding the nav and nav-pills classes will apply pill styling.

只需为页面元素简单的添加data-toggle="tab" 或 data-toggle="pill"就可以无需写任何JavaScript代码也能激活标签页或胶囊式导航。为ul添加.nav和.nav-tabs classe即可为其赋予Bootstrap标签页样式；而添加nav和nav-pills class可以为其赋予胶囊标签页样式。

<!-- Nav tabs -->
<ul class="nav nav-tabs">
  <li><a href="#home" data-toggle="tab">Home</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 panes -->
<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>

渐入效果

为每个.tab-pane添加.fade可以让标签页具有淡入的特效。第一个标签页所对应的的内容区必须也添加.in使初始内容同时具有淡入效果。

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

方法

$().tab

激活标签页和内容区。每个标签页都应该通过data-target 或 href以指定目标内容容器。

<ul class="nav nav-tabs" id="myTab">
  <li class="active"><a href="#home" data-toggle="tab">Home</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>

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

事件

事件类型	描述
show.bs.tab	This event fires on tab show, but before the new tab has been shown. Use `event.target` and `event.relatedTarget` to target the active tab and the previous active tab (if available) respectively.
shown.bs.tab	This event fires on tab show after a tab has been shown. Use `event.target` and `event.relatedTarget` to target the active tab and the previous active tab (if available) respectively.

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

案例

受到Jason Frame开发的jQuery.tipsy插件的启发，我们才把这个工具提示插件做的更好，而且此插件不依赖图片，只是使用CSS3来实现动画效果，并使用data属性存储标题。

将鼠标悬停到下面的链接上就可以看到工具提示了：

四个展示方位

选择性加入的功能

出于性能方面的考虑，工具提示和弹框组件的data属性api是选择性加入的，也就是说你必须自己初始化他们。

工具提示与按钮组和输入框组联合使用时需要一些特殊设置

在.btn-group 或 .input-group内的元素上使用工具提示时，你需要指定container: 'body'选项以避免不需要的副作用（例如，当工具提示显示之后，与其合作的页面元素可能变得更宽或是去圆角）。

在禁止使用的页面元素上使用工具提示时需要额外增加一个元素将其包裹起来

为了给disabled 或.disabled元素添加工具提示，将需要增加工具提示的页面元素包裹在一个<div>中，然后对这个<div>元素应用工具提示。

用法

通过JavaScript激活工具提示：

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

Markup

The generated markup of a tooltip is rather simple, though it does require a position (by default, set to top by the plugin).

<div class="tooltip">
  <div class="tooltip-inner">
    Tooltip!
  </div>
  <div class="tooltip-arrow"></div>
</div>

选项

可以将选项通过data属性或JavaScript传递。对于data属性，需要将选项名称放到data-之后，例如data-animation=""。

名称	类型	默认值	描述
animation	boolean	true	apply a CSS fade transition to the tooltip
html	boolean	false	Insert HTML into the tooltip. If false, jQuery's `text` method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.
placement	string \| function	'top'	how to position the tooltip - top \| bottom \| left \| right \| auto. When "auto" is specified, it will dynamically reorient the tooltip. For example, if placement is "auto left", the tooltip will display to the left when possible, otherwise it will display right.
selector	string	false	If a selector is provided, tooltip objects will be delegated to the specified targets.
title	string \| function	''	default title value if `title` attribute isn't present
trigger	string	'hover focus'	how tooltip is triggered - click \| hover \| focus \| manual. You may pass multiple triggers; separate them with a space.
delay	number \| object	0	delay showing and hiding the tooltip (ms) - does not apply to manual trigger type If a number is supplied, delay is applied to both hide/show Object structure is: `delay: { show: 500, hide: 100 }`
container	string \| false	false	Appends the tooltip to a specific element. Example: `container: 'body'`

对单个工具提示使用data属性

使用data属性可以为单个工具提示指定额外选项，如下所示。

标记

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

事件

事件类型	描述
show.bs.tooltip	当`show`方法被调用之后，此事件将被立即触发。
shown.bs.tooltip	当工具提示展示到用户面前之后（同时CSS过渡效果执行完之后）此事件被触发。
hide.bs.tooltip	当`hide`方法被调用之后，此事件被触发。
hidden.bs.tooltip	当工具提示被隐藏之后（同时CSS过渡效果执行完之后），此事件被触发。

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

案例

为页面内容添加一个小的覆盖层，就像iPad上的效果一样，为页面元素增加额外的信息。

插件依赖

弹出框依赖工具提示插件，因此需要先加载工具提示插件。

选择性加入的功能

出于性能方面的考虑，工具提示和弹框组件的data属性api是选择性加入的，也就是说你必须自己初始化他们。

弹出框在按钮组和输入框组中使用时，需要额外的设置

当提示框与.btn-group 或 .input-group联合使用时，你需要指定container: 'body'选项（见下面的文档）以避免不需要的副作用（例如，当弹出框显示之后，与其合作的页面元素可能变得更宽或是去圆角）。

在禁止使用的页面元素上使用弹出框时需要额外增加一个元素将其包裹起来

为了给disabled 或.disabled元素添加弹出框时，将需要增加弹出框的页面元素包裹在一个<div>中，然后对这个<div>元素应用弹出框。

静态案例

4个可选选项：top、right、bottom,和left排列。

动态演示

Click to toggle popover

四个方向

用法

通过JavaScript启用弹出框：

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

选项

可以将选项通过data属性或JavaScript传递。对于data属性，需要将选项名称放到data-之后，例如data-animation=""。

名称	类型	默认值	描述
animation	boolean	true	apply a CSS fade transition to the tooltip
html	boolean	false	Insert HTML into the popover. If false, jQuery's `text` method will be used to insert content into the DOM. Use text if you're worried about XSS attacks.
placement	string \| function	'right'	how to position the popover - top \| bottom \| left \| right \| auto. When "auto" is specified, it will dynamically reorient the popover. For example, if placement is "auto left", the tooltip will display to the left when possible, otherwise it will display right.
selector	string	false	if a selector is provided, tooltip objects will be delegated to the specified targets. in practice, this is used to enable dynamic HTML content to have popovers added. See this and an informative example.
trigger	string	'click'	how popover is triggered - click \| hover \| focus \| manual
title	string \| function	''	default title value if `title` attribute isn't present
content	string \| function	''	default content value if `data-content` attribute isn't present
delay	number \| object	0	delay showing and hiding the popover (ms) - does not apply to manual trigger type If a number is supplied, delay is applied to both hide/show Object structure is: `delay: { show: 500, hide: 100 }`
container	string \| false	false	Appends the popover to a specific element. Example: `container: 'body'`. This option is particularly useful in that it allows you to position the popover in the flow of the document near the triggering element - which will prevent the popover from floating away from the triggering element during a window resize.

为单个弹出框应用data属性

对单个弹出框可以通过data属性单独指定选项，如上所示。

方法

$().popover(options)

为一组元素初始化弹出框。

.popover('show')

显示弹出框。

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

.popover('hide')

隐藏弹出框。

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

.popover('toggle')

展示或隐藏弹出框。

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

.popover('destroy')

隐藏并销毁弹出框。

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

事件

事件类型	描述
show.bs.popover	当`show`方法被调用之后，此事件将被立即触发。
shown.bs.popover	当弹出框展示到用户面前之后（同时CSS过渡效果执行完之后）此事件被触发。
hide.bs.popover	当`hide`方法被调用之后，此事件被触发。
hidden.bs.popover	当弹出框被隐藏之后（同时CSS过渡效果执行完之后），此事件被触发。

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

案例

通过这个插件可以为所有警告框增加关闭功能。

Holy guacamole! Best check yo self, you're not looking too good.

Oh snap! You got an error!

Change this and that and try again. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Cras mattis consectetur purus sit amet fermentum.

用法

通过JavaScript启用警告框关闭功能：

$(".alert").alert()

标记

只需为关闭按钮设置data-dismiss="alert"即可自动为警告框赋予关闭功能。

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

方法

$().alert()

为所有警告框加入关闭功能。如果希望警告框被关闭时呈现动画效果，请确保为其添加了.fade 和 .in。

.alert('close')

关闭警告框。

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

事件

Bootstrap中的警告框暴露了一组事件，允许你进行监听。

事件类型	描述
close.bs.alert	当`close`函数被调用之后，此事件被立即触发。
closed.bs.alert	当警告框被关闭之后（同时CSS过渡效果执行完毕），此事件被触发。

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

案例

按钮可以完成很多工作。控制按钮状态或创建按钮组可以产生类似工具条之类的复杂组件。

状态

通过添加data-loading-text="正在加载..."可以使按钮呈现加载状态。

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

状态切换

通过添加data-toggle="button"可以让按钮能够切换状态。

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

选择框

通过向按钮组添加data-toggle="buttons"可以使按钮组具有类似选择框的选择/取消功能。

Option 1 Option 2 Option 3

<div class="btn-group" data-toggle="buttons">
  <label class="btn btn-primary">
    <input type="checkbox"> Option 1
  </label>
  <label class="btn btn-primary">
    <input type="checkbox"> Option 2
  </label>
  <label class="btn btn-primary">
    <input type="checkbox"> Option 3
  </label>
</div>

单选

通过向按钮组添加data-toggle="buttons"可以让按钮组具有单选框的功能。

Option 1 Option 2 Option 3

<div class="btn-group" data-toggle="buttons">
  <label class="btn btn-primary">
    <input type="radio" name="options" id="option1"> Option 1
  </label>
  <label class="btn btn-primary">
    <input type="radio" name="options" id="option2"> Option 2
  </label>
  <label class="btn btn-primary">
    <input type="radio" name="options" id="option3"> Option 3
  </label>
</div>

用法

通过JavaScript构建按钮：

$('.btn').button()

标记

按钮插件完整支持data属性。通过下面的案例可以看到各种使用方式。

选项

None

方法

$().button('toggle')

切换按钮状态。赋予按钮被激活时的状态和外观。

自动切换

可以使用data-toggle属性让按钮具有自动切换状态的能力。

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

$().button('loading')

设置按钮状态为loading - 即将按钮置为禁用状态并将文字内容切换为loading。通过使用data-loading-text可以在按钮元素上定义loading文本。

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

跨浏览器兼容性

Firefox会在多个页面加载之间保持按钮的禁用状态。可以通过添加autocomplete="off"来解决提到的问题。

$().button('reset')

重置按钮状态 - 并将按钮上的文本还原为原始值。

$().button(string)

重置按钮状态 - 并将按钮上的文本重置为传入的值。

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

关于

对为支持折叠功能的组件，例如accordions和导航，赋予基本样式和灵活的支持。

插件依赖

折叠插件依赖过渡效果插件。

案例

使用折叠插件，通过扩展panel组件从而构建了一个简单的accordion组件。

Collapsible Group Item #1

Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.

Collapsible Group Item #2

Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.

Collapsible Group Item #3

Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.

<div class="panel-group" id="accordion">
  <div class="panel panel-default">
    <div class="panel-heading">
      <h4 class="panel-title">
        <a data-toggle="collapse" data-toggle="collapse" data-parent="#accordion" href="#collapseOne">
          Collapsible Group Item #1
        </a>
      </h4>
    </div>
    <div id="collapseOne" class="panel-collapse collapse in">
      <div class="panel-body">
        Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
      </div>
    </div>
  </div>
  <div class="panel panel-default">
    <div class="panel-heading">
      <h4 class="panel-title">
        <a data-toggle="collapse" data-toggle="collapse" data-parent="#accordion" href="#collapseTwo">
          Collapsible Group Item #2
        </a>
      </h4>
    </div>
    <div id="collapseTwo" class="panel-collapse collapse">
      <div class="panel-body">
        Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
      </div>
    </div>
  </div>
  <div class="panel panel-default">
    <div class="panel-heading">
      <h4 class="panel-title">
        <a data-toggle="collapse" data-toggle="collapse" data-parent="#accordion" href="#collapseThree">
          Collapsible Group Item #3
        </a>
      </h4>
    </div>
    <div id="collapseThree" class="panel-collapse collapse">
      <div class="panel-body">
        Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
      </div>
    </div>
  </div>
</div>

You can also use the plugin without the accordion markup. Make a button toggle the expanding and collapsing of another element.

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

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

用法

The collapse plugin utilizes a few classes to handle the heavy lifting:

.collapse hides the content
.collapse.in shows the content
.collapsing is added when the transition starts, and removed when it finishes

These classes can be found in component-animations.less.

通过data属性

仅仅通过向页面元素添加data-toggle="collapse" 和data-target就可以为其赋予控制可折叠页面元素的能力。data-target属性接受一个CSS选择器作为其控制对象。请确保为可折叠页面元素添加collapse class。如果你希望可折叠页面元素的默认状态是展开的，请添加in class。

为了给一组可折叠页面元素添加控制器，添加data-parent="#selector"即可。请参考下面给出的案例。

通过JavaScript

手动触发：

$('.collapse').collapse()

选项

可以将选项通过data属性或JavaScript传递。对于data属性，需要将选项名称放到data-之后，例如data-parent=""。

名称	类型	默认值	描述
parent	selector	false	If selector then all collapsible elements under the specified parent will be closed when this collapsible item is shown. (similar to traditional accordion behavior - this dependent on the `accordion-group` class)
toggle	boolean	true	Toggles the collapsible element on invocation

方法

.collapse(options)

赋予页面元素可折叠功能。接受一个可选的object作为参数。

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

.collapse('toggle')

展示或隐藏一个可折叠的页面元素。

.collapse('show')

展示一个可折叠页面元素。

.collapse('hide')

隐藏一个可折叠页面元素。

事件

Bootstrap中的折叠插件对外暴露了一组可以监听的事件。

事件类型	描述
show.bs.collapse	当`show`方法被调用之后立即触发此事件。
shown.bs.collapse	当可折叠页面元素显示出来之后（同时CSS过渡效果也已执行完毕），此事件被触发。
hide.bs.collapse	当`hide`方法被调用之后，此事件被立即触发。
hidden.bs.collapse	当可折叠页面元素隐藏之后（同时CSS过渡效果也已执行完毕），此事件被触发。

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

案例

下面展示的就是此插件和相关组件制作的轮播案例。

<div id="carousel-example-generic" class="carousel slide" data-ride="carousel">
  <!-- Indicators -->
  <ol class="carousel-indicators">
    <li data-target="#carousel-example-generic" data-slide-to="0" class="active"></li>
    <li data-target="#carousel-example-generic" data-slide-to="1"></li>
    <li data-target="#carousel-example-generic" data-slide-to="2"></li>
  </ol>

  <!-- Wrapper for slides -->
  <div class="carousel-inner">
    <div class="item active">
      <img src="..." alt="...">
      <div class="carousel-caption">
        ...
      </div>
    </div>
    ...
  </div>

  <!-- Controls -->
  <a class="left carousel-control" href="#carousel-example-generic" data-slide="prev">
    <span class="glyphicon glyphicon-chevron-left"></span>
  </a>
  <a class="right carousel-control" href="#carousel-example-generic" data-slide="next">
    <span class="glyphicon glyphicon-chevron-right"></span>
  </a>
</div>

Internet Explorer 8 & 9不支持过渡动画效果

Bootstrap基于CSS3实现动画效果，但是Internet Explorer 8 & 9不支持这些必要的CSS属性。因此，使用这两种浏览器时将会丢失过渡动画效果。而且，我们并不打算使用基于jQuery实现替代功能。

可选选项

在任何.item中均可以通过添加.carousel-caption从而为每帧幻灯片添加说明文字。也可以添加任何HTML代码，这些HTML代码将会被自动排列和格式化。

First slide label

Nulla vitae elit libero, a pharetra augue mollis interdum.

Second slide label

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Third slide label

Praesent commodo cursus magna, vel scelerisque nisl consectetur.

<div class="item active">
  <img src="..." alt="...">
  <div class="carousel-caption">
    <h3>...</h3>
    <p>...</p>
  </div>
</div>

可访问性问题

轮播组件并不兼容可访问性标准。如果需要兼容，请考虑其他展示幻灯片的方案。

用法

通过data属性

通过data属性可以很容易的控制轮播的定位。data-slide可以接受控制播放位置的prev或next关键字。另外，还可以通过data-slide-to传递以0开始的幻灯片下标。

data-ride="carousel"属性用来标记在页面加载之后即开始启动的轮播组件。

通过JavaScript

手动启动轮播组件：

$('.carousel').carousel()

选项

可以将选项通过data属性或JavaScript传递。对于data属性，需要将选项名称放到data-之后，例如data-interval=""。

名称	类型	默认值	描述
interval	number	5000	幻灯片轮换的等待时间。如果为false，轮播将不会自动开始循环。
pause	string	"hover"	鼠标停留在幻灯片区域即暂停轮播，鼠标离开即启动轮播。
wrap	boolean	true	轮播是否持续循环。

方法

.carousel(options)

初始化轮播组件，接受一个可选的object类型的options参数，并开始幻灯片循环。

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

.carousel('cycle')

从左到右循环各帧。

.carousel('pause')

停止轮播。

.carousel(number)

将轮播定位到指定的帧上（帧下标以0开始，类似数组）。

.carousel('prev')

返回到上一帧。

.carousel('next')

转到下一帧。

事件

Bootstrap的轮播组件暴露了两个事件用于监听。

事件类型	描述
slide.bs.carousel	此事件在`slide`方法被调用之后立即出发。
slid.bs.carousel	当所有幻灯片播放完之后被触发。

$('#myCarousel').on('slide.bs.carousel', function () {
  // do something…
})

案例

本页面左侧的导航就是affix插件的完整实例。

用法

通过data属性

只需为需要监听的页面元素添加data-spy="affix"即可方便的添加affix行为。然后设置Then use offsets to define when to toggle the pinning of an element on and off.

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

Requires independent styling ;)

Affix插件在三中状态之间切换：affix、affix-top和affix-bottom。你必须为这三种状态提供自己的样式（不依赖此插件）。 affix-top class应当是在正常文档流中的状态。affix class应当是以fixed方式定位时的状态。affix-bottom应当是以absolute方式定位时的状态。注意，affix-bottom在此插件中比较特殊， is special in that the plugin will place the element with JS relative to the offset: { bottom: number } option you've provided.

通过JavaScript

通过JavaScript启动affix插件：

  $('#myAffix').affix({
    offset: {
      top: 100
    , bottom: function () {
        return (this.bottom = $('.bs-footer').outerHeight(true))
      }
    }
  })

选项

可以将选项通过data属性或JavaScript传递。对于data属性，需要将选项名称放到data-之后，例如data-offset-top="200"。

名称	类型	默认值	描述
offset	number \| function \| object	10	Pixels to offset from screen when calculating position of scroll. If a single number is provided, the offset will be applied in both top and bottom directions. To provide a unique, bottom and top offset just provide an object `offset: { top: 10 }` or `offset: { top: 10, bottom: 5 }`. Use a function when you need to dynamically calculate an offset.

JavaScript插件

概览

单个还是全部引入

不要将两份文件全部引入

插件之间的依赖

Data属性

编程式API

避免冲突

事件

第三方工具库

过渡效果transition.js

关于过渡效果

What's inside

模态框 modal.js

案例

不支持模态框重叠

对于移动设备的附加说明

静态案例

Modal title

动态演示

增强模态框的可访问性

用法

通过data属性

通过JavaScript调用

选项

方法

.modal(options)

.modal('toggle')

.modal('show')

.modal('hide')

事件

下拉菜单 dropdown.js

案例

用于导航条

用于标签页

用法

通过data属性

通过JavaScript

选项

方法

$().dropdown('toggle')

事件

滚动监听 scrollspy.js

案例

@fat

@mdo

one

two

three

用法

通过data属性

通过JavaScript

导航链接地址必须有对应的目标

方法

.scrollspy('refresh')

选项

事件

标签页tab.js

案例

扩展了标签页式导航

用法

标记

渐入效果

方法

$().tab

事件

工具提示 tooltip.js

案例

四个展示方位

选择性加入的功能

工具提示与按钮组和输入框组联合使用时需要一些特殊设置

在禁止使用的页面元素上使用工具提示时需要额外增加一个元素将其包裹起来

用法

Markup

选项

对单个工具提示使用data属性

标记

方法

$().tooltip(options)

.tooltip('show')