Menu選單

選單元件提供一組垂直排列的項目。當使用者與按鈕或其他控制項互動時，會顯示選單。

如果你需要建立下拉選單，可以搭配 <mdui-dropdown> 元件。

使用方法

按需引入元件：

import 'mdui/components/menu.js';
import 'mdui/components/menu-item.js';

按需引入元件的 TypeScript 型別：

import type { Menu } from 'mdui/components/menu.js';
import type { MenuItem } from 'mdui/components/menu-item.js';

使用範例：

Item 1

Item 2

<mdui-menu>
  <mdui-menu-item>Item 1</mdui-menu-item>
  <mdui-menu-item>Item 2</mdui-menu-item>
</mdui-menu>

範例

搭配 <mdui-dropdown> 元件來建立下拉選單。

open dropdown

Item 1

Item 2

<mdui-dropdown>
  <mdui-button slot="trigger">open dropdown</mdui-button>
  <mdui-menu>
    <mdui-menu-item>Item 1</mdui-menu-item>
    <mdui-menu-item>Item 2</mdui-menu-item>
  </mdui-menu>
</mdui-dropdown>

原始碼

緊湊佈局

在 <mdui-menu> 元件上加上 dense 屬性，可以做成緊湊佈局。

Item 1

Item 2

Item 3

<mdui-menu dense>
  <mdui-menu-item>Item 1</mdui-menu-item>
  <mdui-menu-item>Item 2</mdui-menu-item>
  <mdui-menu-item>Item 3</mdui-menu-item>
</mdui-menu>

原始碼

停用選單項目

在 <mdui-menu-item> 元件上加上 disabled 屬性，可以停用該選單項目。

Item 1

Item 2

Item 3

<mdui-menu>
  <mdui-menu-item disabled>Item 1</mdui-menu-item>
  <mdui-menu-item>Item 2</mdui-menu-item>
  <mdui-menu-item>Item 3</mdui-menu-item>
</mdui-menu>

原始碼

支援單選

在 <mdui-menu> 元件上指定 selects 屬性為 single，可以做成單選功能。此時 <mdui-menu> 的 value 值即為目前選取的 <mdui-menu-item> 的 value 值。

Item 1

Item 2

<mdui-menu selects="single" value="item-2">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-menu>

原始碼

支援多選

在 <mdui-menu> 元件上指定 selects 屬性為 multiple，可以做成多選功能。此時 <mdui-menu> 的 value 值即為目前選取的 <mdui-menu-item> 的 value 值所組成的陣列。

注意：在多選模式下，<mdui-menu> 的 value 值為陣列，只能透過 JavaScript 屬性來讀取和設定該值。

Item 1

Item 2

Item 3

<mdui-menu selects="multiple" class="example-multiple">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <mdui-menu-item value="item-3">Item 3</mdui-menu-item>
</mdui-menu>

<script>
  // 設定預設選取 item-1 和 item-2
  const menu = document.querySelector(".example-multiple");
  menu.value = ["item-1", "item-2"];
</script>

原始碼

圖示

在 <mdui-menu-item> 元件上，透過設定 icon 和 end-icon 屬性，可以分別在選單項目的左側和右側加入 Material Icons 圖示。透過設定 end-text 屬性，則可以在右側加入文字。此外，也可以透過 icon、end-icon 和 end-text slot 在選單項目的左側和右側加入圖示和文字。

如果需要在選單項目左側空出一個圖示的位置以保持與其他選單項目的對齊，可以將 icon 屬性設定為空字串。

Item 1

Item 2

Ctrl+X

Item 3

<mdui-menu>
  <mdui-menu-item icon="visibility" end-icon="add_circle" end-text="Ctrl+X">Item 1</mdui-menu-item>
  <mdui-menu-item>
    Item 2
    <mdui-icon slot="icon" name="visibility"></mdui-icon>
    <mdui-icon slot="end-icon" name="add_circle"></mdui-icon>
    <span slot="end-text">Ctrl+X</span>
  </mdui-menu-item>
  <mdui-menu-item icon="">Item 3</mdui-menu-item>
</mdui-menu>

原始碼

在單選或多選模式下，可以透過 selected-icon 屬性或 selected-icon slot 設定選取狀態的圖示。

Item 1

Item 2

<mdui-menu selects="multiple">
  <mdui-menu-item value="item-1" selected-icon="cloud_done">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">
    <mdui-icon slot="selected-icon" name="done_outline"></mdui-icon>
    Item 2
  </mdui-menu-item>
</mdui-menu>

原始碼

連結

在 <mdui-menu-item> 元件上設定 href 屬性，即可將選單項目轉為連結，並可使用以下連結相關的屬性：download、target 和 rel。

Item 1

Item 2

<mdui-menu>
  <mdui-menu-item href="https://www.mdui.org" target="_blank">Item 1</mdui-menu-item>
  <mdui-menu-item>Item 2</mdui-menu-item>
</mdui-menu>

原始碼

子選單

在 <mdui-menu-item> 元件中，可以使用 submenu slot 來指定子選單項目的元素。

Line spacing Single

1.5

Double

Custom: 1.2

Paragraph style

<mdui-menu>
  <mdui-menu-item>
    Line spacing
    <mdui-menu-item slot="submenu">Single</mdui-menu-item>
    <mdui-menu-item slot="submenu">1.5</mdui-menu-item>
    <mdui-menu-item slot="submenu">Double</mdui-menu-item>
    <mdui-menu-item slot="submenu">Custom: 1.2</mdui-menu-item>
  </mdui-menu-item>
  <mdui-menu-item>Paragraph style</mdui-menu-item>
</mdui-menu>

原始碼

在 <mdui-menu> 元件上，可以透過 submenu-trigger 屬性設定子選單的觸發方式。

Line spacing Single

1.5

Double

Custom: 1.2

Paragraph style

<mdui-menu submenu-trigger="click">
  <mdui-menu-item>
    Line spacing
    <mdui-menu-item slot="submenu">Single</mdui-menu-item>
    <mdui-menu-item slot="submenu">1.5</mdui-menu-item>
    <mdui-menu-item slot="submenu">Double</mdui-menu-item>
    <mdui-menu-item slot="submenu">Custom: 1.2</mdui-menu-item>
  </mdui-menu-item>
  <mdui-menu-item>Paragraph style</mdui-menu-item>
</mdui-menu>

原始碼

當 submenu-trigger 屬性設定為 hover 時，可以在 <mdui-menu> 元件上透過 submenu-open-delay 和 submenu-close-delay 屬性設定子選單的開啟延遲和關閉延遲。

Line spacing Single

1.5

Double

Custom: 1.2

Paragraph style

<mdui-menu submenu-trigger="hover" submenu-open-delay="1000" submenu-close-delay="1000">
  <mdui-menu-item>
    Line spacing
    <mdui-menu-item slot="submenu">Single</mdui-menu-item>
    <mdui-menu-item slot="submenu">1.5</mdui-menu-item>
    <mdui-menu-item slot="submenu">Double</mdui-menu-item>
    <mdui-menu-item slot="submenu">Custom: 1.2</mdui-menu-item>
  </mdui-menu-item>
  <mdui-menu-item>Paragraph style</mdui-menu-item>
</mdui-menu>

原始碼

自訂內容

在 <mdui-menu-item> 元件中，你可以使用 custom slot 來完全自訂選單項目的內容。

ABS

取數值的絕對值

ACOS

數值的反餘弦值，以弧度表示

ACOSH

數值的反雙曲餘弦值

<style>
  .custom-item {
    padding: 4px 12px;
  }

  .custom-item .secondary {
    display: none;
    color: #888;
    font-size: 13px;
  }

  .custom-item:hover .secondary {
    display: block
  }
</style>

<mdui-menu>
  <mdui-menu-item>
    <div slot="custom" class="custom-item">
      <div>ABS</div>
      <div class="secondary">取數值的絕對值</div>
    </div>
  </mdui-menu-item>
  <mdui-menu-item>
    <div slot="custom" class="custom-item">
      <div>ACOS</div>
      <div class="secondary">數值的反餘弦值，以弧度表示</div>
    </div>
  </mdui-menu-item>
  <mdui-menu-item>
    <div slot="custom" class="custom-item">
      <div>ACOSH</div>
      <div class="secondary">數值的反雙曲餘弦值</div>
    </div>
  </mdui-menu-item>
</mdui-menu>

原始碼

HTML 屬性	JavaScript 屬性	型別	預設值
`value`	`value`	`string`	-
選單項目的值
`disabled`	`disabled`	`boolean`	`false`
是否停用選單項目
`icon`	`icon`	`string`	-
左側的 Material Icons 圖示名。也可以透過 `slot="icon"` 設定如果左側不需要顯示圖示，但需要預留一個圖示的位置，可傳入空字串進行佔位
`end-icon`	`endIcon`	`string`	-
右側的 Material Icons 圖示名。也可以透過 `slot="end-icon"` 設定
`end-text`	`endText`	`string`	-
右側的文字。也可以透過 `slot="end-text"` 設定
`selected-icon`	`selectedIcon`	`string`	-
選取狀態的 Material Icons 圖示名。也可以透過 `slot="selected-icon"` 設定
`submenu-open`	`submenuOpen`	`boolean`	`false`
是否開啟子選單
`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`
失去焦點時觸發
`submenu-open`
子選單開始開啟時，事件被觸發。可以透過呼叫 `event.preventDefault()` 阻止子選單開啟
`submenu-opened`
子選單開啟動畫完成時，事件被觸發
`submenu-close`
子選單開始關閉時，事件被觸發。可以透過呼叫 `event.preventDefault()` 阻止子選單關閉
`submenu-closed`
子選單關閉動畫完成時，事件被觸發

名稱
預設
選單項目的文字
`icon`
選單項目左側圖示
`end-icon`
選單項目右側圖示
`end-text`
選單右側的文字
`selected-icon`
選取狀態的圖示
`submenu`
子選單
`custom`
任意自訂內容

名稱
`container`
選單項目的容器
`icon`
左側的圖示
`label`
文字內容
`end-icon`
右側的圖示
`end-text`
右側的文字
`selected-icon`
選取狀態的圖示
`submenu`
子選單元素

HTML 屬性	JavaScript 屬性	型別	預設值
`selects`	`selects`	`'single' \| 'multiple'`	-
選單項的可選狀態。預設不可選。可選值包括： `single`：單選 `multiple`：多選
`value`	`value`	`string \| string[]`	-
目前選取的 `<mdui-menu-item>` 的值。 Note：該屬性的 HTML 屬性始終為字串，僅在 `selects="single"` 時可透過 HTML 屬性設定初始值；該屬性的 JavaScript 屬性值在 `selects="single"` 時為字串，在 `selects="multiple"` 時為字串陣列。因此，在 `selects="multiple"` 時，若要修改該值，只能透過修改 JavaScript 屬性值來實作。
`dense`	`dense`	`boolean`	`false`
選單項是否使用緊湊版面
`submenu-trigger`	`submenuTrigger`	`'click' \| 'hover' \| 'focus' \| 'manual' \| string`	`'click hover'`
子選單的觸發方式，支援多個值，用空格分隔。可選值包括： `click`：點擊選單項時開啟子選單 `hover`：滑鼠懸停到選單項上時開啟子選單 `focus`：聚焦到選單項上時開啟子選單 `manual`：僅能透過程式方式開啟和關閉子選單，不能再指定其他觸發方式
`submenu-open-delay`	`submenuOpenDelay`	`number`	`200`
滑鼠懸停觸發子選單開啟的延遲，單位毫秒
`submenu-close-delay`	`submenuCloseDelay`	`number`	`200`
滑鼠懸停觸發子選單關閉的延遲，單位毫秒

名稱	參數	回傳值
`focus`	`options: FocusOptions` (選配)	`void`
將焦點設定在目前元素上
`blur`		`void`
從目前元素中移除焦點

名稱
`change`
選單項選取狀態變化時觸發

名稱
預設
子選單項（`<mdui-menu-item>`）、分隔線（`<mdui-divider>`）等元素

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

List 清單

NavigationBar 底部導覽列

Menu選單

使用方法

範例

緊湊佈局

停用選單項目

支援單選

支援多選

圖示

連結

子選單

自訂內容

`mdui-menu-item` API

屬性

方法

事件

Slots

CSS Parts

`mdui-menu` API

屬性

方法

事件

Slots

CSS 自訂屬性