JavaScript

Bootstrap 內含 13 個 jQuery 外掛,它們賦予了元件生命。

ASP.NET Web API 2實戰訓練營 ASP.NET Web API是微軟打造的REST開發框架,可輕易建置HTTP服務,實戰課程拳拳到肉教您如何上場殺敵,K.O.各種用戶端。 SkillTree 報名

單獨或完整的外掛

每個外掛都可以單獨引用(注意各外掛相依性問題)或一次全部引用。bootstrap.jsbootstrap.min.js(最小化) 檔案都包含全部外掛內容。

Data 屬性

你能單純只透過標記 API 而不需要撰寫任何一行 JavaScript 來使用所有 Bootstrap 外掛。這是 Bootstrap 最頂層 API 且應該是你首選使用外掛的方式。

譯者註:first class,直譯可有「第一類別」、「首類別」也有「甲級」、「第一級」的意思,但這裡我譯為「頂層」或「最頂層」。

某些情況,可能需要特意去關閉某些功能或動作,因此,我們也提供了關閉 data 屬性 API,透過解除繫結在 body 上命名空間為 `'data-api'` 的所有事件。如下所示:

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

另一種選擇,解除特定的外掛事件繫結,只需要將外掛名稱後面加上 data-api 即可,如下所示:

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

程式設計 API

我們認為你應該能夠透過 JavaScript API 來使用所有 Bootstrap 外掛。所有公開 API 可以是單一或可鏈接的方法,且回傳所操作的集合。

譯者註:使用方法和 jQuery 的 API 一樣。

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

所有方法都接受一個選擇性參數物件,一個對此方法有特別意義的字串或什麼也不傳(這是外掛預設行為)。

                    $("#myModal").modal()                       // 初始化與採取預設值
$("#myModal").modal({ keyboard: false })   // 初始化與無鍵盤設置
$("#myModal").modal('show')                // 初始化與立即呼叫show
                

每個外掛透過 Constructor 屬性來揭露原始的建構函數:$.fn.popover.Constructor。如果你想取得某個特定外掛的執行個體(instance),可以直接從頁面元素取得:$('[rel=popover]').data('popover')

譯者註:Instance可譯為「執行個體」或「實例」。

不衝突

有時候,你需要同時使用 Bootstrap 外掛和其他 UI 框架。在這種情況下,可能偶爾會發生命名空間衝突。如果發生了這種情況,你可以呼叫外掛的 .noConflict 函數回復預設值。

var bootstrapButton = $.fn.button.noConflict() // 回傳 $.fn.button 的預設值
$.fn.bootstrapBtn = bootstrapButton            // 取得 $().bootstrapBtn Bootstrap 的功能

事件

Bootstrap 對多數外掛的特別行為提供自訂事件。一般而言,這些事件都是以動詞的原型和過去分詞形式來呈現。動詞原型呈現在事件執行之前觸發,例如,show。過去分詞形式呈現在動作執行完畢之後觸發,例如,shown

譯者註:這裡指英文的動詞原型和過去分詞。

所有動詞原型的事件都提供 preventDefault 函數。這能在動作被執行之前停止。

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

關於轉場

一個簡單的轉場效果(transition),只要在引用其他 JavaScript 檔案時一同引用 bootstrap-transition.js 檔案即可。如果你引用的是完整(或最小化)的 bootstrap.js 檔案,就不需要在引用此檔案,因為它已經包含此檔案的內容。

使用情境

一些簡單的範例可以使用轉場效果:

  • 投影片或淡入效果的對話視窗
  • 淡出效果的頁籤
  • 淡出效果的警告視窗
  • 投影片輪播控制面板

譯者註:可參考 CSS3 transitions 以瞭解什麼是轉場效果。另外,從 bootstrap-transition.js 原始碼得知,此檔案只是做瀏覽器是否支援轉場效果的檢測(由 modernizr 提供的功能),主要是提供給 Bootstrap 其他有使用到轉場效果的外掛使用。

範例

對話視窗是一個流線、彈性的視窗,對話提示有最低需求功能和聰明的預設值。

靜態範例

呈現一個有標題、本體和帶有動作的頁尾的對話視窗。

<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>一個好的本體…</p>
  </div>
  <div class="modal-footer">
    <a href="#" class="btn">關閉</a>
    <a href="#" class="btn btn-primary">儲存變更</a>
  </div>
</div>

Live demo

點擊下面的按鈕後透過 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">對話視窗標題</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>

使用方式

經由 data 屬性

要啟用一個對話視窗不需要撰寫 JavaScript。在主要控制元素上,例如,按鈕,設置 data-toggle="modal",然後再設置 data-target="#foo"href="#foo" 用以指向某個對話視窗進行切換。

<button type="button" data-toggle="modal" data-target="#myModal">執行對話視窗</button>

經由 JavaScript

透過一行 JavaScript 來呼叫 id 為 myModal 的對話視窗。

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

選項

上述程式碼裡的 Options 可以經由 data 屬性或 JavaScript 來傳遞。使用 data 屬性,將選項名稱附加於 data- 之後,就像 data-backdrop="" 一樣。

名稱 型別 預設 說明
backdrop boolean true 包含 modal-backdrop 元素。另外,指定 static 背景下,在對話視窗上點擊不會關閉。
keyboard boolean true 當鍵盤 Esc 按鈕被按下關閉對話視窗。
show boolean true 當完成初始化立即呈現對話視窗。
remote path false

如果有提供遠端 URL,內容將會經由 jQuery 的 load 方法載入和注入到 .modal-body 類別元素中。如果你是使用 data api的話,你可能或使用 href 標記來指定遠端資源。例如以下範例所示:

<a data-toggle="modal" href="remote.html" data-target="#modal">點擊我</a>

方法

.modal(options)

讓你的內容變成一個對話視窗。接受一個選擇性選項 object

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

.modal('toggle')

手動切換對話視窗。

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

.modal('show')

手動開啟對話視窗。

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

.modal('hide')

手動隱藏對話視窗。

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

事件

Bootstrap 對話視窗類別有公開一些事件允許監聽。

事件 說明
show show 執行個體的方法被呼叫此事件會立即觸發。
shown 當對話視窗呈現完成至使用者面前(會等待 CSS 轉場效果完成)此事件會被觸發。
hide hide 執行個體的方法被呼叫此事件會立即觸發。
hidden 當對話視窗完從使用者面前完成隱藏(會等待 CSS 轉場效果完成)此事件會被觸發。
$('#myModal').on('hidden', function () {
  // do something…
})

在巡覽列的範例

滑動監視外掛會自動依據滑動位置來更新巡覽列裡的項目。滑動下面區域使其低於巡覽列,然後觀察 active 類別的變化。下拉式選單的子項目會跟著變化高亮度呈現。

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

譯者註:active 類別的變化必須開啟開發者工具來觀察。當滑動接觸到內容的標題(@fat 或 @mdo)時,滑動監視外掛會動態為對應巡覽列裡的 <li> 加入 active 類別,以呈現高亮度效果。例如,本說明文件左方巡覽列即是使用滑動監視外掛達到此效果。


使用方式

經由 data 屬性

很簡單就能加入滑動監視行為到你的頂層巡覽列,只需加入 data-spy="scroll" 到你想監視的元素上(大部分情況是加到 body 上),然後將 data-target=".navbar" 加到想巡覽的部分。你也會想使用滑動監視在 .nav 元件上。

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

經由 JavaScript

透過 JavaScript 呼叫滑動監視:

$('#navbar').scrollspy()
注意!巡覽列的連結必須指定對應的目標 id。例如,<a href="#home">home</a> 連結必須和 DOM 某一元素互相對應,像是 <div id="home"></div>

方法

.scrollspy('refresh')

當使用滑動監視的 DOM 元素有新增或移除操作時,你需要去呼叫 refresh 方法,如下所示:

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

選項

選項能透過 data 屬性或 JavaScript 來傳遞。data 屬性,將選項名稱附加至 data- 後面,例如,data-offset=""

名稱 型別 預設 說明
offset number 10 計算滑動位置時從頂端要位移的像素。

事件

事件 說明
activate 當一個項目被滑動監視設置 activate 類別時,此事件會被觸發。

頁籤範例

快速加入動態的頁籤功能到視窗內以切換本地內容,甚至經由下拉式選單。

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'); // 透過 name 來啟用
$('#myTab a:first').tab('show'); // 選擇第一個(:first)來啟用
$('#myTab a:last').tab('show'); // 選擇最後一個(:last)來啟用
$('#myTab li:eq(2) a').tab('show'); // 選擇第三個當頁籤(索引由 0 開始)

標記

在元素上指定 data-toggle="tab"data-toggle="pill" 即可啟用頁籤或 pill 巡覽而不必撰寫任何 JavaScript。在頁籤的 ul 設置 navnav-tabs 類別即可套用 Bootstrap 頁籤樣式。

<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

啟用一個頁籤元素和內容容器。頁籤應該包含 data-gargethref 屬性且指向 DOM 中某個容器節點。

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

譯者註:注意範例中每個 href="#id-name" 對應至 <div id="name"> 的關係。

事件

事件 說明
show 此事件在頁籤呈現時觸發,但是在新頁籤呈現完成之前。使用 event.target 指向要啟用的頁籤,使用 event.relatedTarget 指向前一個啟用的頁籤(如果有的話)。
shown 此事件在頁籤已經完整呈現之後觸發。使用 event.target 指向要啟用的頁籤,使用 event.relatedTarget 指向前一個啟用的頁籤(如果有的話)。
$('a[data-toggle="tab"]').on('shown', function (e) {
  e.target // activated tab
  e.relatedTarget // previous tab
})

範例

取自 Jason Frame 所撰寫優秀 jQuery.tipsy 外掛得到的靈感;工具提示是一個更新版本,它不依賴圖片,使用 CSS3 的動畫和 data- 屬性來對標題進行本地儲存。

譯者註:本地儲存意思是,將標題的描述放入 title="描述…" 屬性內。

出於性能原因,工具提示和彈出提示 data- API 必須自行宣告,意思是,你必須自行初始化它們

將滑鼠移至連結將可看到工具提示:

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.

四種方向

譯者註:設置 data-placement 類別併指定 top、right、bottom 或 left 其中任一值。

輸入框群組使用工具提示

在 Bootstrap 的輸入框群組使用工具提示和彈出提示,你要設置 container 選項(文件下面說明)來避免不必要的副作用。


使用方式

經由 JavaScript 來觸發工具提示:

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

選項

選項能透過 data 屬性或 JavaScript 來傳遞。data 屬性,將選項名稱附加至 data- 後面,例如,data-animation=""

名稱 型別 預設 說明
animation boolean true 為工具提示加入一個 CSS 淡入轉換的效果。
html boolean false 是否允許插入 HTML 到工具提示裡。如果為 false,jQuery 使用 text 方法來插入內容到 DOM 中。使用 text 你必須担心關於 XSS 功擊。譯者註jQuery .text() 方法
placement string | function 'top' 工具提示的定位位置 - top | bottom | left | right。
selector string false 如果提供 selector,將符合條件的一或多個元件啟用工具提示。
title string | function '' 如果 title 屬性不存在,使用此值做為預設標題。
trigger string 'hover focus' 工具提示觸發方式 - click | hover | focus | manual。注意,你傳遞多個觸發器、空間分隔、觸發類型的情況。

譯者註:click 是點擊觸發;hover 是滑鼠移至觸發;focus 是取得焦點觸發;manual 是手動控制觸發。
delay number | object 0

呈現或隱藏工具提示的延遲時間(毫秒),注意,不要設置到 manual 類型觸發器。

如果提供數字是合法的,延遲設置會同時套用到 hide / show 上。

物件建構式:delay: { show: 500, hide: 100 }

container string | false false

附加工具提示到指定的元素 container: 'body'

注意! 可以針對單獨的工具提示指定單獨的 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')

範例

此與 iPad 類似的功能,為任意元素加入一個小覆蓋層以加入額外資訊。將滑鼠移至下面按鈕以觸發彈出提示。需要包含 工具提示 外掛。

譯者註:舊版說明文件的範例是滑鼠移過按鈕(下面紅色大按鈕)時會呈現彈出提示。但目前筆者翻譯 Bootstrap Version 2.3.2 這個版本的文件範例已改為 click 行為來觸發。應是原作者改寫文件時沒有發現所留下的筆誤。這邊還是保留其翻譯文,但加上刪除線。

靜態彈出提示

有四個方向可選擇: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.

當彈出提示在 data 屬性內從 JavaScript 和內容產生彈出提示時不需要標記。

Live demo

四種方向


使用方式

經由 JavaScript 啟用彈出提示:

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

選項

選項能透過 data 屬性或 JavaScript 來傳遞。data 屬性,將選項名稱附加至 data- 後面,例如,data-animation=""

名稱 型別 預設 說明
animation boolean true 為彈出提示加入一個 CSS 淡入轉換的效果。
html boolean false 是否允許插入 HTML 到工具提示裡。如果為 false,jQuery 使用 text 方法來插入內容到 DOM 中。使用 text 你必須担心關於 XSS 功擊。
placement string | function 'right' 彈出提示的定位位置 - top | bottom | left | right。
selector string false 如果提供 selector,將符合條件的一或多個元件啟用彈出提示。
trigger string 'click' 彈出提示觸發方式 - click | hover | focus | manual。
title string | function '' 如果 title 屬性不存在,使用此值做為預設標題。
content string | function '' 如果 data-content 屬性不存在,使用此值做為預設內容。
delay number | object 0

呈現或隱藏工具提示的延遲時間(毫秒),注意,不要設置到 manual 類型觸發器。

如果提供數字是合法的,延遲設置會同時套用到 hide / show 上。

物件建構式:delay: { show: 500, hide: 100 }

container string | false false

附加彈出提示到指定的元素 container: 'body'

注意!可以針對單獨的彈出提示指定單獨的 data 屬性。

標記

出於性能原因,工具提示和彈出提示 data- API 必須自行宣告。如果你想要使用它們僅需要指定一個 selector 選項。

方法

$().popover(options)

在一組元素上初始化彈出提示。

.popover('show')

呈現某個元素的彈出提示。

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

.popover('hide')

隱藏某個元素的彈出提示。

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

.popover('toggle')

切換彈出提示為呈現或隱藏。

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

.popover('destroy')

隱藏與刪除某個元素的彈出提示。

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

警告視窗範例

利用此外掛對所有警告訊息加入取消功能。 Add dismiss functionality to all alert messages with this plugin.

Holy guacamole! Best check yo self, you're not looking too good.
<div class="bs-docs-example">
  <div class="alert fade in">
    <button type="button" class="close" data-dismiss="alert">×</button>
    <strong>Holy guacamole!</strong> Best check yo self, you're not looking too good.
  </div>
</div>

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.

Take this action Or do this

<div class="bs-docs-example">
  <div class="alert alert-block alert-error fade in">
    <button type="button" class="close" data-dismiss="alert">×</button>
    <h4 class="alert-heading">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>
      <a class="btn btn-danger" href="#">Take this action</a> <a class="btn" href="#">Or do this</a>
    </p>
  </div>
</div>

譯者註:取消功能是最右邊的「X」。


使用方式

經由 JavaScript 來啟用警告視窗的取消功能:

$(".alert").alert()

標記

僅需要加入 data-dismiss="alert" 到你的關閉按鈕,即可自動賦予警告視窗閉關的功能。

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

方法

$().alert()

賦予所有警告視窗關閉功能。如果希望警告視窗在關閉時有動畫效果,請確認它們已設置好 .fade.in 類別。

.alert('close')

關閉警告視窗。

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

事件

Bootstrap 警告視窗類別有公開一些事件允許監聽。

事件 說明
close close 執行個體方法被呼叫此事件立即觸發。
closed 當警告視窗關閉(會等待 CSS 轉場效果完成)此事件會被觸發。
$('#my-alert').bind('closed', function () {
  // do something…
})

使用範例

讓按鈕可以做更多事。控制按鈕的狀態或建立複合元件(像是工具列)的按鈕群組。

有狀態的

加入 data-loading-text="Loading..." 使按鈕呈現載入中的狀態。

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

Checkbox

在 btn-group 加入 data-toggle="buttons-checkbox" 以呈現可切換 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>

Radio

在 btn-group 加入 data-toggle="buttons-radio" 以呈現可切換的 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')

切換按下的狀態。賦予按鈕被啟用時應有的外觀樣式。

注意!你也可以使用 data-toggle 屬性自動啟用可切換狀態。
<button type="button" class="btn" data-toggle="button" >…</button>

$().button('loading')

設置按鈕為載入狀態 - 這會將禁用按鈕和更改文字為 loading。按鈕文字應該使用 data 屬性 data-loading-text 設置在按鈕元素上。

<button type="button" class="btn" data-loading-text="勇者,載入中..." >...</button>
注意! Firefox 跨頁載入時保持禁用的狀態。變通方案是在按鈕上使用 autocomplete="off"

$().button('reset')

重新設置按鈕狀態 - 這會還原按鈕文字。

$().button(string)

重新設置按鈕狀態 - 這會將按鈕文字更改為定義的文字。

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

關於

取得可折疊元件,像是手風琴或巡覽的基礎樣式和彈性的支援。

譯者註:accordion 是手風琴,西方一種常用樂器,延伸意思是可折疊。讀者可以想成東方的扇子

* 需包含 Transition 外掛。

手風琴範例

使用折疊外掛,我們建置一個簡單手風琴樣式小工具:

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="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 屬性

僅需的加入 data-toggle="collapse"data-target 到元素上就能自動指派折疊元素的控制權。data-target 屬採接受一個 CSS 選擇器,以選取元素套用折疊樣式。另外,一定要加入 collapse 類別到可折疊元素上。如果要預設某折疊元素是開啟的,還要額外加入 in 類別。

若要加入手風琴樣式的群組管理到可折疊控制項,需要加入 data 屬性 data-parent="#selector"。請參考上面範例。

譯者註:參考範例中 <a> 元素的 data-parent="#accordion2" 屬性設置,它對應的是外層的 <div>id="accordion2"

經由 JavaScript

可手動啟用可折疊效果:

$(".collapse").collapse()

選項

選項能透過 data 屬性或 JavaScript 來傳遞。data 屬性,將選項名稱附加至 data- 後面,例如,data-parent=""

名稱 型別 預設 說明
parent selector false 如果指定了選擇器,那麼在呈現此折疊項目時,其他所有被選取的元素集合的折疊效果為關閉效果(與手風琴行為類似)。
toggle boolean true 呼叫時切換可折疊元素的折疊效果。

方法

.collapse(options)

將你的內容轉換為一個可折疊元素。接受一個選擇性參數 object

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

.collapse('toggle')

切換可折疊元素的呈現或隱藏。

.collapse('show')

呈現可折疊元素。

.collapse('hide')

隱藏可折疊元素。

事件

Bootstrap 折疊功能有公開一些事件允許監聽。

事件 說明
show show 執行個體方法被呼叫此事件立即觸發。
shown 當折疊效果呈現完成至使用者面前(會等待 CSS 轉場效果完成)此事件會被觸發。
hide hide 執行個體方法被呼叫此事件立即觸發。
hidden 當折疊效果從使用者面前隱藏完成(會等待 CSS 轉場效果完成)此事件會被觸發。
$('#myCollapsible').on('hidden', function () {
  // do something…
})

範例

一個簡單且易於擴充的外掛,讓你快速為任何輸入框建立優雅的提示。

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

譯者註:此範例有設置 data-source 屬性(下面說明),讀者可以試著個別輸入 a-z 會有自動完成的提示。data-source 內容設置為中文也沒有問題。

你也許需要設置 autocomplete="off" 以預防瀏覽器預設選單覆蓋 Bootstrap 輸入提示選單。


使用方式

經由 data 屬性

經由 data 屬性去註冊輸入提示功能到元素上,如同上面範例一樣。

經由 JavaScript

手動呼叫輸入提示:

$('.typeahead').typeahead()

選項

選項能透過 data 屬性或 JavaScript 來傳遞。data 屬性,將選項名稱附加至 data- 後面,例如,data-source=""

名稱 型別 預設 說明
source array, function [ ] 用於查詢的資料來源。可能是一組陣列或字串或函式。函數必須傳遞兩個參數,輸入欄位的 query 值和 process 回呼(callback)函式。函式可能使用非同步來呼叫直接回傳資源來源,或使用同步呼叫,透過 process 回呼函式單一參數。
items number 8 下拉式選單呈現最大項目數。
minLength number 1 觸發自動完成提示所需小最字元數。
matcher function case insensitive 此方法用於決定某個查詢是否符合某個項目。它接受一個參數 item,表示需要測試的查詢項目。透過 this.query 可以取得現在查詢字串。如果查詢結果符合,回傳 Boolean 值 true
sorter function exact match,
case sensitive,
case insensitive
此方法用於排序自動完成提示的結果。它接受一個參數 item,參數的作用範圍在輸入提示的執行個體內。使用 this.query 參考現在的查詢字串。
updater function returns selected item 此方法用於回傳被選擇的項目。它接受一個參數 item,參數的作用範圍在輸入提示的執行個體內。
highlighter function highlights all default matches 此方法用來高亮度提示自動完成的結果。它接受一個參數 item,參數的作用範圍在輸入提示的執行個體內。它應該回傳 html。

方法

.typeahead(options)

初始化輸入框成為輸入提示樣式。

範例

本文件左邊就是一個附加巡覽外掛的展示。

譯者註:本文件最上方是主巡覽最,除首頁外,其他教學文件頁都有左邊附加巡覽(或稱子巡覽、次巡覽)。


使用方式

經由 data 屬性

加入附加巡覽行到任何元素是簡單的,僅需要加入 data-spy="affix" 到你想監聽的元素上。然後使用偏移量來定義何時切換開關元素的釘選。

<div data-spy="affix" data-offset-top="200">...</div>
注意! 你必須管理釘選元素的位置和它直接父元素的行為。位置使用 affixaffix-topaffix-bottom 來控制。記得檢查潛在的可折疊父元素當附加巡覽衝突時,它會從頁面的正常流動中刪除內容。

經由 JavaScript

經由 JavaScript 呼叫附加巡覽外掛:

$('#navbar').affix()

選項

選項能透過 data 屬性或 JavaScript 來傳遞。data 屬性,將選項名稱附加至 data- 後面,例如,data-offset-top="200"

名稱 型別 預設 說明
offset number | function | object 10 捲軸移動時,會從螢幕的像素去計算偏移的位置。如果提供一個數字,那麼偏移會直接套用到 top 和 left。監聽單一方向或多個唯一偏移,僅需提供 offset: { x: 10 } 物件。當你需要動態地提供一個偏移量時,請使用函數。
comments powered by Disqus