列表群組(List group)
列表群組是一個靈活且強大的元件,用於顯示一系列內容。可以修改和擴展它們以支援幾乎任何內容。
基本範例(Basic example)
最基本的列表群組是帶有列表項目和適當類別的無序列表。根據以下選項或您自己的 CSS 進行擴展。
- An item
- A second item
- A third item
- A fourth item
- And a fifth one
<ul class="list-group">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
<li class="list-group-item">A fourth item</li>
<li class="list-group-item">And a fifth one</li>
</ul> 啟用項目(Active items)
在 .list-group-item 上加入 .active 以表示當前的啟用選擇。
- An active item
- A second item
- A third item
- A fourth item
- And a fifth one
<ul class="list-group">
<li class="list-group-item active" aria-current="true">An active item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
<li class="list-group-item">A fourth item</li>
<li class="list-group-item">And a fifth one</li>
</ul> 連結和按鈕(Links and buttons)
使用 <a> 或 <button> 來建立具有懸停、停用和啟用狀態的可操作列表群組項目,方法是加入 .list-group-item-action。我們將這些偽類別分開,以確保由非互動式元素(如 <li> 或 <div>)組成的列表群組不會提供點擊或觸控互動。
透過加入 .disabled 和 aria-disabled="true" 讓 .list-group-item-action 實例顯示為停用狀態,以通知輔助技術該元素已停用。您可能需要額外的 JavaScript 來完全停用連結和按鈕。
請務必不要在此處使用標準的 .btn 類別。
<div class="list-group">
<a href="#" class="list-group-item list-group-item-action active" aria-current="true">
The current link item
</a>
<a href="#" class="list-group-item list-group-item-action">A second link item</a>
<a href="#" class="list-group-item list-group-item-action">A third link item</a>
<a href="#" class="list-group-item list-group-item-action">A fourth link item</a>
<a href="#" class="list-group-item list-group-item-action disabled" aria-disabled="true">A disabled link item</a>
</div> 對於 <button>,您也可以使用 disabled 屬性而非 .disabled 類別。遺憾的是,<a> 不支援 disabled 屬性。
<div class="list-group">
<button type="button" class="list-group-item list-group-item-action active" aria-current="true">
The current button
</button>
<button type="button" class="list-group-item list-group-item-action">A second button item</button>
<button type="button" class="list-group-item list-group-item-action">A third button item</button>
<button type="button" class="list-group-item list-group-item-action">A fourth button item</button>
<button type="button" class="list-group-item list-group-item-action" disabled>A disabled button item</button>
</div> 齊平樣式(Flush)
加入 .list-group-flush 以移除一些邊框和圓角,使列表群組項目在父容器(例如卡片)中邊緣對齊渲染。
- An item
- A second item
- A third item
- A fourth item
- And a fifth one
<ul class="list-group list-group-flush">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
<li class="list-group-item">A fourth item</li>
<li class="list-group-item">And a fifth one</li>
</ul> 編號列表(Numbered)
加入 .list-group-numbered 修飾類別(並選擇性地使用 <ol> 元素)以啟用編號列表群組項目。數字是透過 CSS 產生的(而不是 <ol> 的預設瀏覽器樣式),以便在列表群組項目中更好地放置並允許更好的自訂。
數字是透過 <ol> 上的 counter-reset 產生的,然後使用 counter-increment 和 content 透過 <li> 上的 ::before 偽元素進行樣式設定和放置。
- A list item
- A list item
- A list item
<ol class="list-group list-group-numbered">
<li class="list-group-item">A list item</li>
<li class="list-group-item">A list item</li>
<li class="list-group-item">A list item</li>
</ol> 這些也可以很好地與自訂內容搭配使用。
-
14SubheadingContent for list item
-
14SubheadingContent for list item
-
14SubheadingContent for list item
<ol class="list-group list-group-numbered">
<li class="list-group-item d-flex justify-content-between align-items-start">
<div class="ms-2 me-auto">
<div class="fw-bold">Subheading</div>
Content for list item
</div>
<span class="badge text-bg-primary rounded-pill">14</span>
</li>
<li class="list-group-item d-flex justify-content-between align-items-start">
<div class="ms-2 me-auto">
<div class="fw-bold">Subheading</div>
Content for list item
</div>
<span class="badge text-bg-primary rounded-pill">14</span>
</li>
<li class="list-group-item d-flex justify-content-between align-items-start">
<div class="ms-2 me-auto">
<div class="fw-bold">Subheading</div>
Content for list item
</div>
<span class="badge text-bg-primary rounded-pill">14</span>
</li>
</ol> 水平排列(Horizontal)
加入 .list-group-horizontal 以將列表群組項目的版面配置從垂直變更為跨所有中斷點的水平。或者,選擇響應式變體 .list-group-horizontal-{sm|md|lg|xl|xxl} 以從該中斷點的 min-width 開始使列表群組水平排列。目前水平列表群組無法與齊平列表群組結合使用。
專業提示: 想要水平排列時列表群組項目等寬嗎?在每個列表群組項目上加入 .flex-fill。
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
- An item
- A second item
- A third item
<ul class="list-group list-group-horizontal">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-sm">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-md">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-lg">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-xl">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul>
<ul class="list-group list-group-horizontal-xxl">
<li class="list-group-item">An item</li>
<li class="list-group-item">A second item</li>
<li class="list-group-item">A third item</li>
</ul> 變體(Variants)
注意! 從 v5.3.0 起,list-group-item-variant() Sass mixin 已被棄用。列表群組項目變體現在透過Sass 迴圈覆寫 CSS 變數。
使用情境類別來設定具有狀態背景和顏色的列表項目樣式。
- A simple default list group item
- A simple primary list group item
- A simple secondary list group item
- A simple success list group item
- A simple danger list group item
- A simple warning list group item
- A simple info list group item
- A simple light list group item
- A simple dark list group item
<ul class="list-group">
<li class="list-group-item">A simple default list group item</li>
<li class="list-group-item list-group-item-primary">A simple primary list group item</li>
<li class="list-group-item list-group-item-secondary">A simple secondary list group item</li>
<li class="list-group-item list-group-item-success">A simple success list group item</li>
<li class="list-group-item list-group-item-danger">A simple danger list group item</li>
<li class="list-group-item list-group-item-warning">A simple warning list group item</li>
<li class="list-group-item list-group-item-info">A simple info list group item</li>
<li class="list-group-item list-group-item-light">A simple light list group item</li>
<li class="list-group-item list-group-item-dark">A simple dark list group item</li>
</ul> 用於連結和按鈕(For links and buttons)
情境類別也可以與 <a> 和 <button> 元素的 .list-group-item-action 搭配使用。請注意此處加入了前一個範例中沒有的懸停樣式。也支援 .active 狀態;套用它以表示情境列表群組項目上的啟用選擇。
<div class="list-group">
<a href="#" class="list-group-item list-group-item-action">A simple default list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-primary">A simple primary list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-secondary">A simple secondary list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-success">A simple success list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-danger">A simple danger list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-warning">A simple warning list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-info">A simple info list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-light">A simple light list group item</a>
<a href="#" class="list-group-item list-group-item-action list-group-item-dark">A simple dark list group item</a>
</div> 無障礙提示: 僅使用顏色來傳達意義只提供了視覺指示,這不會傳達給使用輔助技術(如螢幕閱讀器)的使用者。請確保意義從內容本身就很明顯(例如,具有_足夠_色彩對比度的可見文字),或透過替代方式包含,例如使用 .visually-hidden 類別隱藏的額外文字。
搭配標記(With badges)
使用一些通用類別的幫助,在任何列表群組項目中加入標記以顯示未讀數量、活動等。
- A list item 14
- A second list item 2
- A third list item 1
<ul class="list-group">
<li class="list-group-item d-flex justify-content-between align-items-center">
A list item
<span class="badge text-bg-primary rounded-pill">14</span>
</li>
<li class="list-group-item d-flex justify-content-between align-items-center">
A second list item
<span class="badge text-bg-primary rounded-pill">2</span>
</li>
<li class="list-group-item d-flex justify-content-between align-items-center">
A third list item
<span class="badge text-bg-primary rounded-pill">1</span>
</li>
</ul> 自訂內容(Custom content)
透過 flexbox 通用類別的幫助,在其中加入幾乎任何 HTML,即使是像下面這樣的連結列表群組也可以。
List group item heading
3 days agoSome placeholder content in a paragraph.
And some small print.List group item heading
3 days agoSome placeholder content in a paragraph.
And some muted small print.List group item heading
3 days agoSome placeholder content in a paragraph.
And some muted small print.<div class="list-group">
<a href="#" class="list-group-item list-group-item-action active" aria-current="true">
<div class="d-flex w-100 justify-content-between">
<h5 class="mb-1">List group item heading</h5>
<small>3 days ago</small>
</div>
<p class="mb-1">Some placeholder content in a paragraph.</p>
<small>And some small print.</small>
</a>
<a href="#" class="list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-between">
<h5 class="mb-1">List group item heading</h5>
<small class="text-body-secondary">3 days ago</small>
</div>
<p class="mb-1">Some placeholder content in a paragraph.</p>
<small class="text-body-secondary">And some muted small print.</small>
</a>
<a href="#" class="list-group-item list-group-item-action">
<div class="d-flex w-100 justify-content-between">
<h5 class="mb-1">List group item heading</h5>
<small class="text-body-secondary">3 days ago</small>
</div>
<p class="mb-1">Some placeholder content in a paragraph.</p>
<small class="text-body-secondary">And some muted small print.</small>
</a>
</div> 核取方塊和單選按鈕(Checkboxes and radios)
將 Bootstrap 的核取方塊和單選按鈕放在列表群組項目中並根據需要自訂。您可以在沒有 <label> 的情況下使用它們,但請記得包含 aria-label 屬性和值以確保無障礙。
<ul class="list-group">
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="firstCheckbox">
<label class="form-check-label" for="firstCheckbox">First checkbox</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="secondCheckbox">
<label class="form-check-label" for="secondCheckbox">Second checkbox</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="thirdCheckbox">
<label class="form-check-label" for="thirdCheckbox">Third checkbox</label>
</li>
</ul> <ul class="list-group">
<li class="list-group-item">
<input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="firstRadio" checked>
<label class="form-check-label" for="firstRadio">First radio</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="secondRadio">
<label class="form-check-label" for="secondRadio">Second radio</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="radio" name="listGroupRadio" value="" id="thirdRadio">
<label class="form-check-label" for="thirdRadio">Third radio</label>
</li>
</ul> 您可以在 <label> 上使用 .stretched-link 讓整個列表群組項目可點擊。
<ul class="list-group">
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="firstCheckboxStretched">
<label class="form-check-label stretched-link" for="firstCheckboxStretched">First checkbox</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="secondCheckboxStretched">
<label class="form-check-label stretched-link" for="secondCheckboxStretched">Second checkbox</label>
</li>
<li class="list-group-item">
<input class="form-check-input me-1" type="checkbox" value="" id="thirdCheckboxStretched">
<label class="form-check-label stretched-link" for="thirdCheckboxStretched">Third checkbox</label>
</li>
</ul> CSS
變數(Variables)
Added in v5.2.0作為 Bootstrap 持續演進的 CSS 變數方法的一部分,列表群組現在在 .list-group 上使用本地 CSS 變數來增強即時自訂功能。CSS 變數的值透過 Sass 設定,因此 Sass 自訂仍然受支援。
--#{$prefix}list-group-color: #{$list-group-color};
--#{$prefix}list-group-bg: #{$list-group-bg};
--#{$prefix}list-group-border-color: #{$list-group-border-color};
--#{$prefix}list-group-border-width: #{$list-group-border-width};
--#{$prefix}list-group-border-radius: #{$list-group-border-radius};
--#{$prefix}list-group-item-padding-x: #{$list-group-item-padding-x};
--#{$prefix}list-group-item-padding-y: #{$list-group-item-padding-y};
--#{$prefix}list-group-action-color: #{$list-group-action-color};
--#{$prefix}list-group-action-hover-color: #{$list-group-action-hover-color};
--#{$prefix}list-group-action-hover-bg: #{$list-group-hover-bg};
--#{$prefix}list-group-action-active-color: #{$list-group-action-active-color};
--#{$prefix}list-group-action-active-bg: #{$list-group-action-active-bg};
--#{$prefix}list-group-disabled-color: #{$list-group-disabled-color};
--#{$prefix}list-group-disabled-bg: #{$list-group-disabled-bg};
--#{$prefix}list-group-active-color: #{$list-group-active-color};
--#{$prefix}list-group-active-bg: #{$list-group-active-bg};
--#{$prefix}list-group-active-border-color: #{$list-group-active-border-color};
Sass 變數(Sass variables)
$list-group-color: var(--#{$prefix}body-color);
$list-group-bg: var(--#{$prefix}body-bg);
$list-group-border-color: var(--#{$prefix}border-color);
$list-group-border-width: var(--#{$prefix}border-width);
$list-group-border-radius: var(--#{$prefix}border-radius);
$list-group-item-padding-y: $spacer * .5;
$list-group-item-padding-x: $spacer;
// fusv-disable
$list-group-item-bg-scale: -80%; // Deprecated in v5.3.0
$list-group-item-color-scale: 40%; // Deprecated in v5.3.0
// fusv-enable
$list-group-hover-bg: var(--#{$prefix}tertiary-bg);
$list-group-active-color: $component-active-color;
$list-group-active-bg: $component-active-bg;
$list-group-active-border-color: $list-group-active-bg;
$list-group-disabled-color: var(--#{$prefix}secondary-color);
$list-group-disabled-bg: $list-group-bg;
$list-group-action-color: var(--#{$prefix}secondary-color);
$list-group-action-hover-color: var(--#{$prefix}emphasis-color);
$list-group-action-active-color: var(--#{$prefix}body-color);
$list-group-action-active-bg: var(--#{$prefix}secondary-bg);
Sass mixins
Deprecated in v5.3.0@mixin list-group-item-variant($state, $background, $color) {
.list-group-item-#{$state} {
color: $color;
background-color: $background;
&.list-group-item-action {
&:hover,
&:focus {
color: $color;
background-color: shade-color($background, 10%);
}
&.active {
color: $white;
background-color: $color;
border-color: $color;
}
}
}
}
Sass 迴圈(Sass loops)
透過覆寫 CSS 變數產生修飾類別的迴圈。
// List group contextual variants
//
// Add modifier classes to change text and background color on individual items.
// Organizationally, this must come after the `:hover` states.
@each $state in map-keys($theme-colors) {
.list-group-item-#{$state} {
--#{$prefix}list-group-color: var(--#{$prefix}#{$state}-text-emphasis);
--#{$prefix}list-group-bg: var(--#{$prefix}#{$state}-bg-subtle);
--#{$prefix}list-group-border-color: var(--#{$prefix}#{$state}-border-subtle);
--#{$prefix}list-group-action-hover-color: var(--#{$prefix}emphasis-color);
--#{$prefix}list-group-action-hover-bg: var(--#{$prefix}#{$state}-border-subtle);
--#{$prefix}list-group-action-active-color: var(--#{$prefix}emphasis-color);
--#{$prefix}list-group-action-active-bg: var(--#{$prefix}#{$state}-border-subtle);
--#{$prefix}list-group-active-color: var(--#{$prefix}#{$state}-bg-subtle);
--#{$prefix}list-group-active-bg: var(--#{$prefix}#{$state}-text-emphasis);
--#{$prefix}list-group-active-border-color: var(--#{$prefix}#{$state}-text-emphasis);
}
}
JavaScript 行為(JavaScript behavior)
使用分頁 JavaScript 外掛——單獨引入或透過編譯的 bootstrap.js 檔案——來擴展我們的列表群組以建立可切換的本地內容面板。
<div class="row">
<div class="col-4">
<div class="list-group" id="list-tab" role="tablist">
<a class="list-group-item list-group-item-action active" id="list-home-list" data-bs-toggle="list" href="#list-home" role="tab" aria-controls="list-home">Home</a>
<a class="list-group-item list-group-item-action" id="list-profile-list" data-bs-toggle="list" href="#list-profile" role="tab" aria-controls="list-profile">Profile</a>
<a class="list-group-item list-group-item-action" id="list-messages-list" data-bs-toggle="list" href="#list-messages" role="tab" aria-controls="list-messages">Messages</a>
<a class="list-group-item list-group-item-action" id="list-settings-list" data-bs-toggle="list" href="#list-settings" role="tab" aria-controls="list-settings">Settings</a>
</div>
</div>
<div class="col-8">
<div class="tab-content" id="nav-tabContent">
<div class="tab-pane fade show active" id="list-home" role="tabpanel" aria-labelledby="list-home-list">...</div>
<div class="tab-pane fade" id="list-profile" role="tabpanel" aria-labelledby="list-profile-list">...</div>
<div class="tab-pane fade" id="list-messages" role="tabpanel" aria-labelledby="list-messages-list">...</div>
<div class="tab-pane fade" id="list-settings" role="tabpanel" aria-labelledby="list-settings-list">...</div>
</div>
</div>
</div>
使用 data 屬性(Using data attributes)
您可以透過簡單地在元素上指定 data-bs-toggle="list" 來啟用列表群組導覽,而無需編寫任何 JavaScript。在 .list-group-item 上使用這些 data 屬性。
<div role="tabpanel">
<!-- List group -->
<div class="list-group" id="myList" role="tablist">
<a class="list-group-item list-group-item-action active" data-bs-toggle="list" href="#home" role="tab">Home</a>
<a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#profile" role="tab">Profile</a>
<a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#messages" role="tab">Messages</a>
<a class="list-group-item list-group-item-action" data-bs-toggle="list" href="#settings" role="tab">Settings</a>
</div>
<!-- Tab panes -->
<div class="tab-content">
<div class="tab-pane active" id="home" role="tabpanel">...</div>
<div class="tab-pane" id="profile" role="tabpanel">...</div>
<div class="tab-pane" id="messages" role="tabpanel">...</div>
<div class="tab-pane" id="settings" role="tabpanel">...</div>
</div>
</div>
透過 JavaScript(Via JavaScript)
透過 JavaScript 啟用可切換的列表項目(每個列表項目需要單獨啟用):
const triggerTabList = document.querySelectorAll('#myTab a')
triggerTabList.forEach(triggerEl => {
const tabTrigger = new bootstrap.Tab(triggerEl)
triggerEl.addEventListener('click', event => {
event.preventDefault()
tabTrigger.show()
})
})
您可以透過多種方式啟用個別列表項目:
const triggerEl = document.querySelector('#myTab a[href="#profile"]')
bootstrap.Tab.getInstance(triggerEl).show() // Select tab by name
const triggerFirstTabEl = document.querySelector('#myTab li:first-child a')
bootstrap.Tab.getInstance(triggerFirstTabEl).show() // Select first tab
淡入效果(Fade effect)
要讓分頁面板淡入,請在每個 .tab-pane 上加入 .fade。第一個分頁面板也必須加入 .show 以使初始內容可見。
<div class="tab-content">
<div class="tab-pane fade show active" id="home" role="tabpanel">...</div>
<div class="tab-pane fade" id="profile" role="tabpanel">...</div>
<div class="tab-pane fade" id="messages" role="tabpanel">...</div>
<div class="tab-pane fade" id="settings" role="tabpanel">...</div>
</div>
方法(Methods)
所有 API 方法都是非同步的,並會啟動一個過渡效果。 它們會在過渡開始後立即回傳給呼叫者,但在過渡結束之前。此外,對正在過渡中的元件進行方法呼叫將被忽略。在我們的 JavaScript 文件中了解更多。
將您的內容啟用為分頁元素。
您可以使用建構函式建立分頁實例,例如:
const bsTab = new bootstrap.Tab('#myTab')
| 方法 | 說明 |
|---|---|
dispose | 銷毀元素的分頁。 |
getInstance | 靜態方法,允許您取得與 DOM 元素關聯的分頁實例,您可以這樣使用:bootstrap.Tab.getInstance(element)。 |
getOrCreateInstance | 靜態方法,返回與 DOM 元素關聯的分頁實例,如果尚未初始化則建立一個新的。您可以這樣使用:bootstrap.Tab.getOrCreateInstance(element)。 |
show | 選擇給定的分頁並顯示其關聯的面板。任何先前選擇的其他分頁將變為未選擇狀態,其關聯的面板會被隱藏。在分頁面板實際顯示之前返回給呼叫者(即在 shown.bs.tab 事件發生之前)。 |
事件(Events)
當顯示新分頁時,事件按以下順序觸發:
hide.bs.tab(在當前啟用的分頁上)show.bs.tab(在即將顯示的分頁上)hidden.bs.tab(在先前啟用的分頁上,與hide.bs.tab事件相同)shown.bs.tab(在新啟用的剛顯示的分頁上,與show.bs.tab事件相同)
如果沒有分頁已經處於啟用狀態,則不會觸發 hide.bs.tab 和 hidden.bs.tab 事件。
| 事件類型 | 說明 |
|---|---|
hide.bs.tab | 當新分頁即將顯示(因此先前的啟用分頁即將隱藏)時,此事件會觸發。使用 event.target 和 event.relatedTarget 分別定位當前啟用的分頁和即將啟用的新分頁。 |
hidden.bs.tab | 當新分頁顯示後(因此先前的啟用分頁已隱藏)此事件會觸發。使用 event.target 和 event.relatedTarget 分別定位先前的啟用分頁和新的啟用分頁。 |
show.bs.tab | 此事件在分頁顯示時觸發,但在新分頁顯示之前。使用 event.target 和 event.relatedTarget 分別定位啟用的分頁和先前的啟用分頁(如果有的話)。 |
shown.bs.tab | 此事件在分頁顯示後觸發。使用 event.target 和 event.relatedTarget 分別定位啟用的分頁和先前的啟用分頁(如果有的話)。 |
const tabElms = document.querySelectorAll('a[data-bs-toggle="list"]')
tabElms.forEach(tabElm => {
tabElm.addEventListener('shown.bs.tab', event => {
event.target // newly activated tab
event.relatedTarget // previous active tab
})
})