NavigationBar底部導覽列

導覽列用來讓使用者在行動端頁面中快速切換幾個主要頁面。

使用方法

按需引入元件：

import 'mdui/components/navigation-bar.js';
import 'mdui/components/navigation-bar-item.js';

按需引入元件的 TypeScript 型別：

import type { NavigationBar } from 'mdui/components/navigation-bar.js';
import type { NavigationBarItem } from 'mdui/components/navigation-bar-item.js';

使用範例：（範例中的 style="position: relative" 僅供示意，實際使用時請移除該樣式。）

Item 1

Item 2

Item 3

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
</mdui-navigation-bar>

注意事項：

該元件預設使用 position: fixed 定位，並會自動在 body 上加入 padding-bottom 樣式，以防止頁面內容被元件遮擋。但在以下兩種情況下，會預設使用 position: absolute 定位：

當指定了 scroll-target 屬性時。此時會在 scroll-target 的元素上加入 padding-bottom 樣式。
當元件位於 <mdui-layout></mdui-layout> 中時。此時不會加入 padding-bottom 樣式。

範例

文字標籤顯示狀態

導覽列中的文字標籤預設會在導覽項目數小於等於 3 個時始終顯示；當導覽項目數大於 3 個時，則只顯示選取狀態的文字。

Item 1

Item 2

Item 3

Item 1

Item 2

Item 3

Item 4

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
</mdui-navigation-bar>

<br/>

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="directions_railway" value="item-3">Item 3</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-4">Item 4</mdui-navigation-bar-item>
</mdui-navigation-bar>

原始碼

你可以透過在 <mdui-navigation-bar> 元件上設定 label-visibility 屬性來調整文字標籤的顯示狀態。可選值有：

selected：僅顯示選取狀態的文字
labeled：始終顯示文字
unlabeled：始終不顯示文字

Item 1

Item 2

Item 3

selected

labeled

unlabeled

<mdui-navigation-bar value="item-1" label-visibility="selected" style="position: relative" class="example-label">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
</mdui-navigation-bar>

<mdui-segmented-button-group value="selected" selects="single" style="margin-top: 16px">
  <mdui-segmented-button value="selected">selected</mdui-segmented-button>
  <mdui-segmented-button value="labeled">labeled</mdui-segmented-button>
  <mdui-segmented-button value="unlabeled">unlabeled</mdui-segmented-button>
</mdui-segmented-button-group>

<script>
  const navigationBar = document.querySelector(".example-label");
  const segmentedButtonGroup = navigationBar.nextElementSibling;

  segmentedButtonGroup.addEventListener("change", (event) => {
    navigationBar.labelVisibility = event.target.value;
  });
</script>

原始碼

位於指定容器內

預設情況下，導覽列會固定在頁面底部。

如果你希望將導覽列放在指定的容器內，可以在 <mdui-navigation-bar> 元件上指定 scroll-target 屬性。該屬性的值應為可捲動內容容器的 CSS 選擇器或 DOM 元素。此時，導覽列會以父元素作為定位基準（你需要自行替父元素加上 position: relative; overflow: hidden 樣式）。

Item 1

Item 2

Item 3

頁面內容

<div style="position: relative;overflow: hidden">
  <mdui-navigation-bar scroll-target=".example-scroll-target" value="item-1">
    <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
  </mdui-navigation-bar>

  <div class="example-scroll-target" style="height: 160px;overflow: auto;">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

捲動時隱藏

透過在 <mdui-navigation-bar> 元件上將 scroll-behavior 設為 hide，即可在頁面向下捲動時隱藏導覽列，向上捲動時顯示導覽列。

你可以使用 scroll-threshold 屬性，設定捲動多少像素後開始隱藏導覽列。

Item 1

Item 2

Item 3

頁面內容

<div style="position: relative;overflow: hidden">
  <mdui-navigation-bar
    scroll-behavior="hide"
    scroll-threshold="30"
    scroll-target=".example-scroll-behavior"
    value="item-1"
  >
    <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
  </mdui-navigation-bar>

  <div class="example-scroll-behavior" style="height: 160px;overflow: auto;">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

圖示

在 <mdui-navigation-bar-item> 元件上，icon 屬性用來設定未啟用狀態的導覽項圖示，active-icon 屬性則用來設定啟用狀態的導覽項圖示。也可以透過 icon 和 active-icon slot 來設定未啟用和啟用狀態的圖示元素。

Item 1

Item 2

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item
    icon="place--outlined"
    active-icon="place"
    value="item-1"
  >Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item value="item-2">
    Item 2
    <mdui-icon slot="icon" name="people--outlined"></mdui-icon>
    <mdui-icon slot="active-icon" name="people"></mdui-icon>
  </mdui-navigation-bar-item>
</mdui-navigation-bar>

原始碼

連結

在 <mdui-navigation-bar-item> 元件上設定 href 屬性，可以將導覽項變為連結。此時，還可以使用與連結相關的屬性：download、target、rel。

Item 1

Item 2

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" href="https://www.mdui.org" target="_blank" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
</mdui-navigation-bar>

原始碼

徽章

在 <mdui-navigation-bar-item> 元件中，可以透過 badge slot 加入徽章。

Item 1 99+

Item 2

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">
    Item 1
    <mdui-badge slot="badge">99+</mdui-badge>
  </mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
</mdui-navigation-bar>

原始碼

HTML 屬性	JavaScript 屬性	型別	預設值
`icon`	`icon`	`string`	-
未啟用狀態的 Material Icons 圖示名。也可以透過 `slot="icon"` 設定
`active-icon`	`activeIcon`	`string`	-
啟用狀態的 Material Icons 圖示名。也可以透過 `slot="active-icon"` 設定
`value`	`value`	`string`	-
導覽項的值
`href`	`href`	`string`	-
連結的目標 URL。若設定此屬性，元件內部將渲染為 `<a>` 元素，並可以使用連結相關的屬性。
`download`	`download`	`string`	-
下載連結的目標。 Note：僅在設定了 `href` 屬性時，此屬性才有效。
`target`	`target`	`'_blank' \| '_parent' \| '_self' \| '_top'`	-
連結的開啟方式。可選值包括： `_blank`：在新視窗中開啟連結 `_parent`：在父框架中開啟連結 `_self`：預設。在目前框架中開啟連結 `_top`：在整個視窗中開啟連結 Note：僅在設定了 `href` 屬性時，此屬性才有效。
`rel`	`rel`	`'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'`	-
目前文件與被連結文件之間的關係。可選值包括： `alternate`：目前文件的替代版本 `author`：目前文件或文章的作者 `bookmark`：永久連結到最近的祖先章節 `external`：引用的文件與目前文件不在同一站點 `help`：連結到相關的說明文件 `license`：目前文件的主要內容由被引用文件的版權許可覆蓋 `me`：目前文件代表連結內容的所有者 `next`：目前文件是系列中的一部分，被引用的文件是系列的下一個文件 `nofollow`：目前文件的作者或發布者不認可被引用的文件 `noreferrer`：不包含 `Referer` 標頭。類似於 `noopener` 的效果 `opener`：如果超連結會建立一個頂級瀏覽上下文（即 `target` 屬性值為 `_blank`），則建立一個輔助瀏覽上下文 `prev`：目前文件是系列的一部分，被引用的文件是系列的上一個文件 `search`：提供一個資源連結，可用於搜尋目前檔案及其相關頁面 `tag`：提供一個適用於目前文件的標籤（由給定位址識別） Note：僅在指定了 `href` 屬性時可用。
`autofocus`	`autofocus`	`boolean`	`false`
是否在頁面載入完成後自動取得焦點
`tabindex`	`tabIndex`	`number`	-
元素在使用 Tab 鍵切換焦點時的順序

名稱	參數	回傳值
`click`		`void`
模擬滑鼠點擊元素
`focus`	`options: FocusOptions` (選配)	`void`
將焦點設定到目前元素。可以傳入一個物件作為引數，該物件的屬性包括： `preventScroll`：預設情況下，元素取得焦點後，頁面會捲動以將該元素捲動到檢視中。如果不希望頁面捲動，可以將此屬性設定為 `true`。
`blur`		`void`
移除目前元素的焦點

名稱
`focus`
取得焦點時觸發
`blur`
失去焦點時觸發

名稱
預設
導覽項文字
`icon`
圖示
`active-icon`
啟用狀態的圖示元素
`badge`
徽章

名稱
`container`
導覽項容器
`indicator`
指示器
`badge`
徽章
`icon`
圖示
`active-icon`
啟用狀態的圖示
`label`
導覽項文字

名稱
`--shape-corner-indicator`
指示器的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌

HTML 屬性	JavaScript 屬性	型別	預設值
`hide`	`hide`	`boolean`	`false`
是否隱藏
`label-visibility`	`labelVisibility`	`'auto' \| 'selected' \| 'labeled' \| 'unlabeled'`	`'auto'`
文字的可視狀態。可選值包括： `auto`：當選項小於等於3個時，始終顯示文字；當選項大於3個時，僅顯示選取狀態的文字 `selected`：僅在選取狀態顯示文字 `labeled`：始終顯示文字 `unlabeled`：始終不顯示文字
`value`	`value`	`string`	-
目前選取的 `<mdui-navigation-bar-item>` 的值
`scroll-behavior`	`scrollBehavior`	`'hide' \| 'shrink' \| 'elevate'`	-
捲動行為。可選值包括： `hide`：捲動時隱藏
`scroll-target`	`scrollTarget`	`string \| HTMLElement \| JQ<HTMLElement>`	-
需要監聽捲動事件的目標元素。值可以是 CSS 選擇器、DOM 元素、或 JQ 物件。預設監聽 `window` 的捲動事件
`scroll-threshold`	`scrollThreshold`	`number`	-
觸發捲動行為所需的捲動距離，單位為 `px`
`order`	`order`	`number`	-
該元件在 `<mdui-layout>` 中的版面順序，按從小到大排序。預設為 `0`

名稱
`change`
值變化時觸發
`show`
開始顯示時觸發。可透過呼叫 `event.preventDefault()` 阻止顯示
`shown`
顯示動畫完成時，事件被觸發
`hide`
開始隱藏時觸發。可透過呼叫 `event.preventDefault()` 阻止隱藏
`hidden`
隱藏動畫完成時，事件被觸發

名稱
預設
`<mdui-navigation-bar-item>` 元件

名稱
`--shape-corner`
元件的圓角大小。可以指定一個具體的像素值；但更推薦引用設計令牌
`--z-index`
元件的 CSS `z-index` 值

Menu 選單

NavigationDrawer 導覽抽屜

NavigationBar底部導覽列

使用方法

範例

文字標籤顯示狀態

位於指定容器內

捲動時隱藏

圖示

連結

徽章

`mdui-navigation-bar-item` API

屬性

方法

事件

Slots

CSS Parts

CSS 自訂屬性

`mdui-navigation-bar` API

屬性

事件

Slots

CSS 自訂屬性