NavigationRail側邊導覽列

側邊導覽列為平板電腦和桌上型電腦提供了存取不同主頁面的方式。

使用方法

按需引入元件：

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

按需引入元件的 TypeScript 型別：

import type { NavigationRail } from 'mdui/components/navigation-rail.js';
import type { NavigationRailItem } from 'mdui/components/navigation-rail-item.js';

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

Recent

Images

Library

<mdui-navigation-rail value="recent" style="position: relative">
  <mdui-navigation-rail-item icon="watch_later--outlined" value="recent">Recent</mdui-navigation-rail-item>
  <mdui-navigation-rail-item icon="image--outlined" value="images">Images</mdui-navigation-rail-item>
  <mdui-navigation-rail-item icon="library_music--outlined" value="library">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>

注意事項：

該元件預設使用 position: fixed 定位，並會自動在 body 上加入 padding-left 或 padding-right 樣式，以防止頁面內容被該元件遮擋。

但在以下兩種情況下，會預設使用 position: absolute 定位：

<mdui-navigation-rail> 元件的 contained 屬性為 true 時。此時會在父元素上加入 padding-left 或 padding-right 樣式。
當位於 <mdui-layout></mdui-layout> 元件中時。此時不會加入 padding-left 或 padding-right 樣式。

範例

位於指定容器內

預設情況下，側邊導覽列會固定在頁面左側或右側。如果你希望將側邊導覽列放在指定的容器內，可以在 <mdui-navigation-rail> 元件上加上 contained 屬性，此時側邊導覽列會以其父元素作為定位基準（你需要自行替父元素加上 position: relative 樣式）。

Recent

Images

Library

頁面內容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

位於右側

在 <mdui-navigation-rail> 元件上設定 placement 屬性為 right，可以將側邊導覽列顯示在右側。

Recent

Images

Library

頁面內容

<div style="position: relative">
  <mdui-navigation-rail placement="right" contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

顯示分割線

在 <mdui-navigation-rail> 元件上加上 divider 屬性，可以在側邊導覽列上加入一條分割線，以便和頁面內容區分開。

Recent

Images

Library

頁面內容

<div style="position: relative">
  <mdui-navigation-rail divider contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

在頂部/底部加入元素

你可以在 <mdui-navigation-rail> 元件內透過 top、bottom slot 在頂部和底部加入元素。

Recent

Images

Library

頁面內容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-button-icon icon="menu" slot="top"></mdui-button-icon>
    <mdui-fab lowered icon="edit--outlined" slot="top"></mdui-fab>
    <mdui-button-icon icon="settings" slot="bottom"></mdui-button-icon>

    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 600px;overflow: auto">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

導覽項垂直對齊方式

透過設定 <mdui-navigation-rail> 元件的 alignment 屬性，可以修改導覽項的垂直對齊方式。

Recent

Images

Library

start

center

end

<div class="example-alignment" style="position: relative">
  <mdui-navigation-rail alignment="start" contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 360px;overflow: auto">
    <mdui-segmented-button-group value="start" selects="single">
      <mdui-segmented-button value="start">start</mdui-segmented-button>
      <mdui-segmented-button value="center">center</mdui-segmented-button>
      <mdui-segmented-button value="end">end</mdui-segmented-button>
    </mdui-segmented-button-group>
  </div>
</div>

<script>
  const example = document.querySelector(".example-alignment");
  const navigationRail = example.querySelector("mdui-navigation-rail");
  const segmentedButtonGroup = example.querySelector("mdui-segmented-button-group");

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

原始碼

圖示

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

Recent

Images

Library

頁面內容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined" active-icon="image--filled">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item>
      Library
      <mdui-icon slot="icon" name="library_music--outlined"></mdui-icon>
      <mdui-icon slot="active-icon" name="library_music--filled"></mdui-icon>
    </mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

僅使用圖示

<mdui-navigation-rail-item> 元件可以僅使用圖示，不加入文字。

頁面內容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-navigation-rail-item icon="watch_later--outlined"></mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined"></mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined"></mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

連結

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

Recent

Images

Library

頁面內容

<div style="position: relative">
  <mdui-navigation-rail divider contained>
    <mdui-navigation-rail-item
      href="https://www.mdui.org"
      target="_blank"
      icon="watch_later--outlined"
    >Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

徽章

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

Recent 99+

Images

Library

頁面內容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">
      Recent
      <mdui-badge slot="badge">99+</mdui-badge>
    </mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">頁面內容</div>
  </div>
</div>

原始碼

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 屬性	型別	預設值
`value`	`value`	`string`	-
目前選取的 `<mdui-navigation-rail-item>` 的值
`placement`	`placement`	`'left' \| 'right'`	`'left'`
導覽列的位置。可選值包括： `left`：左側 `right`：右側
`alignment`	`alignment`	`'start' \| 'center' \| 'end'`	`'start'`
`<mdui-navigation-rail-item>` 元素的對齊方式。可選值包括： `start`：頂部對齊 `center`：置中對齊 `end`：底部對齊
`contained`	`contained`	`boolean`	`false`
預設情況下，導覽列相對於 `body` 元素顯示。當該屬性設定為 `true` 時，導覽列將相對於其父元素顯示。 Note：設定該屬性時，必須在父元素上手動設定樣式 `position: relative;`。
`divider`	`divider`	`boolean`	`false`
是否在導覽列和頁面內容之間新增分隔線
`order`	`order`	`number`	-
該元件在 `<mdui-layout>` 中的版面順序，按從小到大排序。預設為 `0`

名稱
`change`
值變化時觸發

名稱
預設
`<mdui-navigation-rail-item>` 元件
`top`
頂部的元素
`bottom`
底部的元素

名稱
`top`
頂部元素的容器
`bottom`
底部元素的容器
`items`
`<mdui-navigation-rail-item>` 元件的容器

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

NavigationDrawer 導覽抽屜

Radio 單選按鈕

NavigationRail側邊導覽列

使用方法

範例

位於指定容器內

位於右側

顯示分割線

在頂部/底部加入元素

導覽項垂直對齊方式

圖示

僅使用圖示

連結

徽章

`mdui-navigation-rail-item` API

屬性

方法

事件

Slots

CSS Parts

CSS 自訂屬性

`mdui-navigation-rail` API

屬性

事件

Slots

CSS Parts

CSS 自訂屬性