JavaScript 插件手册

jQuery 插件为 Bootstrap 的组件赋予了“生命”。可以简单地一次性引入所有插件,或者逐个引入到你的页面中。


单个还是全部引入

JavaScript 插件可以单个引入(使用 Bootstrap 提供的单个 *.js 文件),或者一次性全部引入(使用 bootstrap.js 或压缩版的 bootstrap.min.js)。


建议使用压缩版的 JavaScript 文件

bootstrap.jsbootstrap.min.js 都包含了所有插件,你在使用时,只需选择一个引入页面就可以了。区别是:一个没有压缩,一个进行了压缩。


组件的 data 属性

不要在同一个元素上同时使用多个插件的 data 属性。例如,button 组件不能同时支持工具提示和控制模态框。如果需要的话,可以在其外面包裹一个额外的元素。


插件之间的依赖关系

某些插件和 CSS 组件依赖于其它插件。如果你是单个引入每个插件的,请确保在文档中检查插件之间的依赖关系。注意,所有插件都依赖 jQuery (也就是说,jQuery必须在所有插件之前引入页面)。 bower.json 文件中列出了 Bootstrap 所支持的 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 })   // initialized with no keyboard
$('#myModal').modal('show')                // 初始化后立即调用 show 方法

每个插件还通过 Constructor 属性暴露了其原始的构造函数:$.fn.popover.Constructor。如果你想获取某个插件的实例,可以直接通过页面元素获取:$('[rel=“popover”]').data('popover')


默认设置

每个插件都可以通过修改其自身的 Constructor.DEFAULTS 对象从而改变插件的默认设置:

$.fn.modal.Constructor.DEFAULTS.keyboard = false // 将模态框插件的 `keyboard` 默认选参数置为 false

避免命名空间冲突

某些时候可能需要将 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 )表示在动作执行完毕之后被触发。

从 3.0.0 版本开始,所有 Bootstrap 事件的名称都采用命名空间方式。

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

$('#myModal').on('show.bs.modal', function (e) {
  if (!data) return e.preventDefault() // 阻止模态框的展示
})

浏览器的 JavaScript 被禁用的情况

Bootstrap 插件未对禁用 JavaScript 的浏览器提供补救措施。如果你对这种情况下的用户体验很关心的话,请添加 <noscript> 标签向你的用户进行解释(并告诉他们如何启用 JavaScript),或者按照你自己的方式提供补救措施。


第三方工具库

Bootstrap 官方不提供对第三方 JavaScript 工具库的支持,例如 Prototype 或 jQuery UI。除了 .noConflict 和为事件名称添加命名空间,还可能会有兼容性方面的问题,这就需要你自己来处理了。


关于过渡效果

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

包含的内容

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


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


不支持模态框重叠

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


模态框的 HTML 代码放置的位置

务必将模态框的 HTML 代码放在文档的最高层级内(也就是说,尽量作为 body 标签的直接子元素),以避免其他组件影响模态框的展现和/或功能。


对于移动设备的附加说明

这里提供了在移动设备上使用模态框有一些附加说明。请参考浏览器支持章节。

由于HTML5如何定义其语义,自动对焦的HTML属性引导模式没有影响。(Due to how HTML5 defines its semantics, the autofocus HTML attribute has no effect in Bootstrap modals.)


模态框:实例

静态实例

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

演示:


<div class="modal fade">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></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 type="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"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></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>
  </div>
</div>

增强模态框的可访问性

务必为 .modal 添加 role=“dialog” 属性,aria-labelledby=“myModalLabel” 属性用于只想模态框的标题栏,aria-hidden=“true” 用于通知辅助性工具略过模态框的 DOM元素。

另外,你还应该通过 aria-describedby 属性为模态框 .modal 添加描述性信息。


嵌入 YouTube 视频(天朝无用)

在模态框中嵌入 YouTube 视频需要增加一些额外的 JavaScript 代码,用于自动停止重放等功能,这些代码并没有在 Bootstrap 中提供。请参考这份发布在 Stack Overflow 上的文章


可选尺寸

模态框提供了两个可选尺寸,通过为 .modal-dialog 增加一个样式调整类实现。

演示:



<!-- Large modal -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bs-example-modal-lg">Large modal</button>
 
<div class="modal fade bs-example-modal-lg" tabindex="-1" role="dialog" aria-labelledby="myLargeModalLabel" aria-hidden="true">
  <div class="modal-dialog modal-lg">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>
 
<!-- Small modal -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bs-example-modal-sm">Small modal</button>
 
<div class="modal fade bs-example-modal-sm" tabindex="-1" role="dialog" aria-labelledby="mySmallModalLabel" aria-hidden="true">
  <div class="modal-dialog modal-sm">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

禁止动画效果

如果你不需要模态框弹出时的动画效果(淡入淡出效果),删掉 .fade 类即可。

<div class="modal" tabindex="-1" role="dialog" aria-labelledby="" aria-hidden="true">
  ...
</div>

模态框:用法

通过 data 属性或 JavaScript 调用模态框插件,可以根据需要动态展示隐藏的内容。模态框弹出时还会为 <body> 元素添加 .modal-open 类,从而覆盖页面默认的滚动行为,并且还会自动生成一个 .modal-backdrop 元素用于提供一个可点击的区域,点击此区域就即可关闭模态框。


模态框: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
或 字符串
'static'
true Includes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.
keyboard boolean true 键盘上的 esc 键被按下时关闭模态框。
show boolean true 模态框初始化之后就立即显示出来。
remote path false This option is deprecated since v3.2.1 and will be removed in v4. We recommend instead using client-side templating or a data binding framework, or calling jQuery.load yourself.

如果提供的是 URL,将利用 jQuery 的 load 方法从此 URL 地址加载要展示的内容(只加载一次) 并插入 .modal-content 内。如果使用的是 data 属性 API,还可以利用 href 属性指定内容来源地址。下面是一个实例:

<a data-toggle=“modal” href=“remote.html” data-target=“#modal”>Click me</a>

模态框:方法

.modal(options)

将页面中的某块内容作为模态框激活。接受可选参数 object

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

.modal('toggle')

手动启动或隐藏模态框。在模态框真正显示或隐藏前返回到调用函数 (也就是,在触发 shown.bs.modalhidden.bs.modal 事件发生之前)。

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

.modal('show')

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

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

.modal('hide')

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

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

模态框:事件

Bootstrap 的模态框类提供了一些事件用于监听并执行你自己的代码。

事件类型 描述
show.bs.modal show 方法调用之后立即触发该事件。如果是通过点击某个作为触发器的元素,则此元素可以通过事件的 relatedTarget 属性进行访问。
shown.bs.modal 此事件在模态框已经显示出来(并且同时在 CSS 过渡效果完成)之后被触发。如果是通过点击某个作为触发器的元素,则此元素可以通过事件的 relatedTarget 属性进行访问。
hide.bs.modal hide 方法调用之后立即触发该事件。
hidden.bs.modal 此事件在模态框被隐藏(并且同时在 CSS 过渡效果完成)之后被触发。
loaded.bs.modal 远端的数据源 加载完数据之后触发该事件。
$('#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" data-target="#" href="http://example.com" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    Dropdown trigger
    <span class="caret"></span>
  </a>
 
  <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
    ...
  </ul>
</div>

下拉:JavaScript 调用

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

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

下拉:选项

None


下拉:方法

$().dropdown('toggle')  //为导航条或标签页式导航打开或关闭下拉菜单。

下拉:事件

All dropdown events are fired at the .dropdown-menu's parent element.

Event Type Description
show.bs.dropdown This event fires immediately when the show instance method is called. The toggling anchor element is available as the relatedTarget property of the event.
shown.bs.dropdown This event is fired when the dropdown has been made visible to the user (will wait for CSS transitions, to complete). The toggling anchor element is available as the relatedTarget property of the event.
hide.bs.dropdown This event is fired immediately when the hide instance method has been called. The toggling anchor element is available as the relatedTarget property of the event.
hidden.bs.dropdown This event is fired when the dropdown has finished being hidden from the user (will wait for CSS transitions, to complete). The toggling anchor element is available as the relatedTarget property of the event.
$('#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>,也可是其他容器标签,如:<div>)添加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.


扩展了标签页式导航

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


标签页:用法

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

对应标记

只需为页面tag导航元素简单的添加data-toggle=“tab”data-toggle=“pill”就可以无需写任何JavaScript代码也能激活标签页或胶囊式导航。为ul添加.nav.nav-tabs classe即可为其赋予Bootstrap标签页样式;而添加navnav-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-targethref以指定目标内容容器。

<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属性存储标题。

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


演示:


Tight pants next level keffiyeh you probably haven't heard of them. Photo booth beard raw denim letterpress vegan messenger bag stumptown. Farm-to-table seitan, mcsweeney's fixie sustainable quinoa 8-bit american apparel have a terry richardson vinyl chambray. Beard stumptown, cardigans banh mi lomo thundercats. Tofu biodiesel williamsburg marfa, four loko mcsweeney's cleanse vegan chambray. A really ironic artisan whatever keytar, scenester farm-to-table banksy Austin twitter handle freegan cred raw denim single-origin coffee viral.


四个展示方位



提示:用法

通过JavaScript激活工具提示:

//激活单个
$("#xxx a").tooltip(); 
 
//激活一个区块 所有带 data-toggle="tooltip" 属性的
$('.tooltip-demo').tooltip({
      selector: '[data-toggle=tooltip]',
      container: 'body'
    })

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
container string / false false
Appends the tooltip to a specific element. Example: container: 'body'. This option is particularly useful in that it allows you to position the tooltip in the flow of the document near the triggering element - which will prevent the tooltip from floating away from the triggering element during a window resize.
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 }
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.

When a function is used to determine the placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The this context is set to the tooltip instance.
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 tooltips added. See this and an informative example.
template string '<div class=“tooltip” role=“tooltip”><div class=“tooltip-arrow”></div><div class=“tooltip-inner”></div></div>'
Base HTML to use when creating the tooltip.

The tooltip's title will be injected into the .tooltip-inner.

.tooltip-arrow will become the tooltip's arrow.

The outermost wrapper element should have the .tooltip class.
title string / function ''
Default title value if title attribute isn't present.

If a function is given, it will be called with its this reference set to the element that the tooltip is attached to.
trigger string 'hover focus' How tooltip is triggered - click / hover / focus / manual. You may pass multiple triggers; separate them with a space.
viewport string / object { selector: 'body', padding: 0 }
Keeps the tooltip within the bounds of this element. Example: viewport: '#viewport' or { “selector”: “#viewport”, “padding”: 0 }

单个标记

对单个工具提示使用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排列。


Popover top

Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.

Popover right

Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.

Popover bottom

Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.

Popover left

Sed posuere consectetur est at lobortis. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum.


弹出框:动态演示


Click to toggle popover


四个方向



弹出框:用法

通过JavaScript启用弹出框:

$('#example').popover();
//或
$('[data-toggle=popover]').popover();

弹出框:选项

可以将选项通过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.


<div class="alert alert-warning fade in">
	<button type="button" class="close" data-dismiss="alert" aria-hidden="true">&times;</button>
	<strong>Holy guacamole!</strong> Best check yo self, you're not looking too good. 
</div>

<div class="alert alert-danger fade in">
	<button type="button" class="close" data-dismiss="alert" aria-hidden="true">&times;</button>
	<h4>Oh snap! You got an error!</h4>
	<p>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.</p>
	<p>
	<button type="button" class="btn btn-danger">Take this action</button>
	<button type="button" class="btn btn-default">Or do this</button>
	</p>
</div>

警告框:用法

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

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


:!: 跨浏览器兼容性
Firefox会在多个页面加载之间保持按钮的禁用状态。可以通过添加autocomplete=“off”来解决提到的问题。


按钮:实例


按钮:加载状态

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



<button type="button" id="myButton" data-loading-text="Loading..." class="btn btn-primary" autocomplete="off">
  Loading state
</button>
 
<script>
  $('#myButton').on('click', function () {
    var $btn = $(this).button('loading')
    // business logic...
    $btn.button('reset')
  })
</script>

按钮:状态切换

通过添加data-toggle=“button”可以让按钮能够切换状态。选择后 会自动向<button>标签内 添加 .active类 和 aria-pressed=“true” 属性。



<button type="button" class="btn btn-primary" data-toggle="button" aria-pressed="false" autocomplete="off">
  Single toggle
</button>

按钮:复选状态

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

Add data-toggle=“buttons” to a .btn-group containing checkbox or radio inputs to enable toggling in their respective styles.


默认选中 .active 向需要激活(默认选中)的按钮label 添加 .active 类,即可使按钮为默认选中状态。



<div class="btn-group" data-toggle="buttons">
  <label class="btn btn-primary active">
    <input type="checkbox" autocomplete="off" checked> Checkbox 1 (pre-checked)
  </label>
  <label class="btn btn-primary">
    <input type="checkbox" autocomplete="off"> Checkbox 2
  </label>
  <label class="btn btn-primary">
    <input type="checkbox" autocomplete="off"> Checkbox 3
  </label>
</div>

按钮:单选状态

通过向按钮组添加data-toggle=“buttons”可以让按钮组具有单选框的功能。<input type=“radio”>



<div class="btn-group" data-toggle="buttons">
  <label class="btn btn-primary active">
    <input type="radio" name="options" id="option1" autocomplete="off" checked> Radio 1 (preselected)
  </label>
  <label class="btn btn-primary">
    <input type="radio" name="options" id="option2" autocomplete="off"> Radio 2
  </label>
  <label class="btn btn-primary">
    <input type="radio" name="options" id="option3" autocomplete="off"> Radio 3
  </label>
</div>

按钮:用法

通过JavaScript构建按钮:

$('.btn').button()

按钮:方法


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


$().button('reset')

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


$().button(string)

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

<button type="button" id="myStateButton" data-complete-text="finished!" class="btn btn-primary" autocomplete="off">
  ...
</button>
 
<script>
  $('#myStateButton').on('click', function () {
    $(this).button('complete') // button text will be "finished!"
  })
</script>

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

LOL 插件依赖: 折叠插件依赖过渡效果插件


折叠:实例

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


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.
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.
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">
        ...
      </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">
        ...
      </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">
        ...
      </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=“”


折叠:方法


.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" role="listbox">
    <div class="item active">
      <img src="..." alt="...">
      <div class="carousel-caption">
        ...
      </div>
    </div>
    <div class="item">
      <img src="..." alt="...">
      <div class="carousel-caption">
        ...
      </div>
    </div>
    ...
  </div>
 
  <!-- Controls -->
  <a class="left carousel-control" href="#carousel-example-generic" role="button" data-slide="prev">
    <span class="glyphicon glyphicon-chevron-left"></span>
    <span class="sr-only">Previous</span>
  </a>
  <a class="right carousel-control" href="#carousel-example-generic" role="button" data-slide="next">
    <span class="glyphicon glyphicon-chevron-right"></span>
    <span class="sr-only">Next</span>
  </a>
</div>

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

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


轮播:用法


轮播:data属性

通过data属性可以很容易的控制轮播的定位。data-slide 可以接受控制播放位置的prevnext 关键字。另外,还可以通过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…
})

Affi:案例

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


Affi:用法


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

Affi:JavaScript调用

通过JavaScript启动affix插件:

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

Affi:选项

可以将选项通过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.