单独或整体

插件可以单独被添加(有些有可能需要依赖), 或一次性全部导入. bootstrap.js 或 bootstrap.min.js 文件中, 包含了所有插件.

数据属性

你可以通过API的标记使用所有Bootstrap插件, 而无需编写单行的JavaScript. 这是Bootstrap最好的API, 并这是使用插件时, 应该是你首先要考虑的.

也就是说, 在某些情况下, 应该要把这项功能关闭. 因此, 我们还提供了禁用数据属性的能力, 就是解除命名空间为 `'data-api'`的所有事件. 看起来像这样:

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

另外, 针对特定插件只需把插件名称连同data-api命名空间. 像这样:

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

使用API

我们也相信你可以完全通过JavaScript API使用Bootstrap所有插件. 所有公共API都是单一, 可链接使用, 和在行为上返回集合.

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

所有方法都应该接受一个可选的对象, 一个字符串, 或什么也不传入(这样会使用插件的默认行为):

$("#myModal").modal()                       // 默认初始化
$("#myModal").modal({ keyboard: false })   // 初始化没有键盘
$("#myModal").modal('show')                // 初始化立即显示

每个插件都在`Constructor`属性公开了其构造函数: $.fn.popover.Constructor. 如果你想获得一个特定插件实例, 可直接从一个元素获取它: $('[rel=popover]').data('popover').

没冲突

有时在使用Bootstrap插件, 还需要使用其他UI框架. 在这种情况下, 命名空间冲突的情况时有发生. 假如发生了冲突情况, 你可以在插件调用 .noConflict.

var bootstrapButton = $.fn.button.noConflict() // 返回 $.fn.button 之前指定的值
$.fn.bootstrapBtn = bootstrapButton            // 给Bootstrap添加 $().bootstrapBtn 功能

事件

Bootstrap对大多数插件独有的行为提供自定义事件. 通常用不定式和过去分词, 如不定式(ex. show)触发事件开始, 和过去分词(ex. shown)触发事件完成.

所有不定式都提供了preventDefault功能. 这能在开始之前终止行为.

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

关于过渡

对于简单的过渡效果, 需要包含一个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>来自XieMin博客的消息</h3>
  </div>
  <div class="modal-body">
    <p>欢迎光临？</p>
  </div>
  <div class="modal-footer">
    <a href="#" class="btn">关闭</a>
    <a href="#" class="btn btn-primary">确定</a>
  </div>
</div>

演示

点击下面按钮, 通过JavaScript触发一个对话框. 它会在页面顶部向下滑入并且伴随着淡入效果.

<!-- Button to trigger modal -->
<a href="#myModal" role="button" class="btn" data-toggle="modal">Launch demo 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">来自XieMin博客的消息</h3>
  </div>
  <div class="modal-body">
    <p>内容内容内容</p>
  </div>
  <div class="modal-footer">
    <button class="btn" data-dismiss="modal" aria-hidden="true">关闭</button>
    <button class="btn btn-primary">确定</button>
  </div>
</div>

用法

使用数据属性

无需写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)

选项

选项的传递可通过数据属性或JavaScript. 对于数据属性, 需要附加选项名称 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-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')

切换导航或标签式导航的菜单.

使用在导航的例子

该插件根据滚动条的位置, 自动更新导航条选项的目标. 滚动导航条下方的区域并观察变化. 同样的, 下拉菜单的子项也会被高亮显示出来.

用法

使用数据属性

可以很容易的在顶部导航条添加监听滚动功能, 只需把data-spy="scroll"添加到你想监听的元素(最典型的就是添加到body)并添加data-target=".navbar"来选择使用哪个导航. 你将会希望在.nav组件使用监听滚动功能.

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

使用JavaScript

通过JavaScript调用监听滚动:

$('#navbar').scrollspy()

方法

.scrollspy('refresh')

如果监听滚动和添加移除节点连同一起使用, 你需要调用refresh方法, 像这样:

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

选项

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

事件

例子

通过不同的内容的过渡, 添加快速, 动态标签功能. 甚至还可以通过下拉菜单实现.

用法

通过JavaScript启用可切换标签 (每个标签都需要单独激活):

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

你可以以多种方式激活标签:

$('#myTab a[href="#profile"]').tab('show'); // 通过名字选择
$('#myTab a:first').tab('show'); // 选择第一个标签
$('#myTab a:last').tab('show'); // 选择最后一个标签
$('#myTab li:eq(2) a').tab('show'); // 选择第三个标签

标记

你可以无需写任何JavaScript来激活标签式或圆角式的导航, 只需在元素上简单的指定 data-toggle="tab" 或 data-toggle="pill". 在标签 ul 添加 nav 和 nav-tabs 属性, 将应用Bootstrap标签样式.

<ul class="nav nav-tabs">
  <li><a href="#home" data-toggle="tab">首页</a></li>
  <li><a href="#profile" data-toggle="tab">简介</a></li>
  <li><a href="#messages" data-toggle="tab">信息</a></li>
  <li><a href="#settings" data-toggle="tab">设置</a></li>
</ul>

方法

$().tab

激活标签元素和内容容器. 因此标签必须具有 data-target 或者 href .

<ul class="nav nav-tabs" id="myTab">
  <li class="active"><a href="#home">首页</a></li>
  <li><a href="#profile">简介</a></li>
  <li><a href="#messages">信息</a></li>
  <li><a href="#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 // 当前活动的标签
  e.relatedTarget // 上一个选择的标签
})

例子

受由Jason Frame开发的优秀jQuery.tipsy插件的启发; 提示工具是一个更好的版本, 它不依赖于图像, 使用CSS3动画和数据属性作为本地数据存储.

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

拥有四个方向

用法

使用JavaScript:

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

选项

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

标记

对于性能方面的考虑, 提示工具和提示框都建议使用data-api. 假如你想使用他们, 只需指定一个选择器选项.

<a href="#" rel="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查看二级信息的效果相像. 将鼠标停悬在按钮上触发提示框. 需要包括 提示工具 .

静态提示框

提供四个方向: 上, 右, 下, 左

由JavaScript和内容包含在data属性所产生的提示框可以无需写标记.

演示

四个方向

用法

使用JavaScript:

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

选项

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

标记

对于性能方面的考虑, 提示工具和提示框都建议使用data-api. 假如你想使用他们, 只需指定一个选择器选项.

方法

$().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…
})

例子

让按钮做的更多. 控制按钮的状态或创建更多组件, 如工具栏的按钮组.

状态式

在按钮添加 data-loading-text="Loading..." 使用加载状态.

<button type="button" class="btn btn-primary" data-loading-text="提交中...">提交</button>

切换

在按钮添加 data-toggle="button" 使用切换.

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

复选框

添加 data-toggle="buttons-checkbox" 让按钮组具有复选框风格按钮.

<div class="btn-group" data-toggle="buttons-checkbox">
  <button type="button" class="btn btn-primary">左</button>
  <button type="button" class="btn btn-primary">中</button>
  <button type="button" class="btn btn-primary">右</button>
</div>

单选框

添加 data-toggle="buttons-radio" 让按钮组具有单选框风格按钮.

<div class="btn-group" data-toggle="buttons-radio">
  <button type="button" class="btn btn-primary">左</button>
  <button type="button" class="btn btn-primary">中</button>
  <button type="button" class="btn btn-primary">右</button>
</div>

用法

使用JavaScript:

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

标记

数据属性是按钮插件的组成部分. 下面的代码实例为各种标记类型.

选项

没有

方法

$().button('toggle')

切换状态. 使按钮的外观被激活.

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

$().button('loading')

设置加载状态的按钮 - 禁用按钮, 并且文本换成加载状态的文本. 加载状态的文本应该在 data-loading-text 属性被定义.

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

$().button('reset')

重置按钮的状态 - 显示原始文本.

$().button(string)

重置按钮的状态 - 显示定义的文本.

<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">
        iPod shuffle
      </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">
        iPod nano
      </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-toggle="collapse" 和 data-target 就能实现一个可折叠的元素. data-target 属性接受一个CSS选择器. 确保在可折叠元素上添加 collapse 属性. 如果你想它默认是打开的, 可以再添加一个 in 属性.

如需要添加一个手风琴式可折叠组, 则需添加 data-parent="#selector". 详情可查看上面的演示.

使用JavaScript

手动调用:

$(".collapse").collapse()

选项

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

方法

.collapse(options)

内容以一个可折叠元素激活. 接受一个object的可选选项.

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

.collapse('toggle')

切换可折叠元素的显示或隐藏.

.collapse('show')

显示可折叠元素.

.collapse('hide')

隐藏可折叠元素.

事件

Bootstrap的切换类提供了一些事件和通知功能挂钩.

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

例子

下面的幻灯片展示了一个通用的插件和组件.

一

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.

二

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.

三

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

用法

使用数据属性

...

使用JavaScript

手动调用:

$('.carousel').carousel()

选项

选项的传递可通过数据属性或JavaScript. 对于数据属性, 需要附加选项名称 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">

用法

使用数据属性

添加一个数据元素注册一个具有输入提醒功能的元素. 如上面例子所示.

使用JavaScript

手动调用:

$('.typeahead').typeahead()

选项

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

方法

.typeahead(options)

把输入框初始化具有输入提示功能.

例子

子导航, 正如左边的导航所示.

用法

使用数据属性

添加附加导航同意简单, 只需把 data-spy="affix" 添加到你想监视的元素上. 然后使用偏移量来确定一个元素的开和关.

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

使用JavaScript

通过JavaScript调用:

$('#navbar').affix()

方法

.affix('refresh')

当使用该插件结合在DOM上添加或删除元素, 此时你需要使用refresh方法:

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

选项

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