TopAppBar頂部應用程式列

頂部應用程式列用來在頁面頂部顯示關鍵資訊與相關操作，提供清楚的導覽和方便的功能存取。

使用方法

按需引入元件：

import 'mdui/components/top-app-bar.js';
import 'mdui/components/top-app-bar-title.js';

按需引入元件的 TypeScript 型別：

import type { TopAppBar } from 'mdui/components/top-app-bar.js';
import type { TopAppBarTitle } from 'mdui/components/top-app-bar-title.js';

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

Title

<mdui-top-app-bar style="position: relative;">
  <mdui-button-icon icon="menu"></mdui-button-icon>
  <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
  <div style="flex-grow: 1"></div>
  <mdui-button-icon icon="more_vert"></mdui-button-icon>
</mdui-top-app-bar>

注意事項：

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

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

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

範例

位於指定容器內

預設情況下，頂部應用程式列會固定在頁面頂部。

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

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar scroll-target=".example-scroll-target">
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
  </mdui-top-app-bar>

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

原始碼

樣式

可以透過在 <mdui-top-app-bar> 元件上使用 variant 屬性來設定頂部應用程式列的樣式。

Title

center-aligned

small

medium

large

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar variant="small" scroll-target=".example-variant" class="example-variant-bar">
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

  <div class="example-variant" style="height: 160px;overflow: auto;">
    <div style="height: 1000px">
      <mdui-segmented-button-group selects="single" value="small">
        <mdui-segmented-button value="center-aligned">center-aligned</mdui-segmented-button>
        <mdui-segmented-button value="small">small</mdui-segmented-button>
        <mdui-segmented-button value="medium">medium</mdui-segmented-button>
        <mdui-segmented-button value="large">large</mdui-segmented-button>
      </mdui-segmented-button-group>
    </div>
  </div>
</div>

<script>
  const topAppBar = document.querySelector(".example-variant-bar");
  const segmentedButtonGroup = document.querySelector(".example-variant");

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

原始碼

頁面捲動時的行為

透過在 <mdui-top-app-bar> 元件上設定 scroll-behavior 屬性，可以定義頁面捲動時頂部應用程式列的行為。可以同時設定多個行為，用空格分隔即可。

捲動行為包括：

hide：頁面向下捲動時隱藏頂部應用程式列，向上捲動時顯示頂部應用程式列。
shrink：僅在 variant 屬性為 medium 或 large 時有效。頁面向下捲動時展開頂部應用程式列，向上捲動時收合頂部應用程式列。
elevate：頁面向下捲動時，在頂部應用程式列上加入陰影；頁面捲回頂部時，取消陰影。

使用 scroll-threshold 屬性，可以設定捲動多少像素後開始觸發頂部應用程式列的捲動行為。（注意，為了確保即時反應，在使用了 elevate 捲動行為時，請不要再設定 scroll-threshold 屬性。）

範例：捲動時隱藏

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    scroll-behavior="hide"
    scroll-threshold="30"
    scroll-target=".example-scroll-behavior-hide"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

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

原始碼

範例：捲動時加入陰影

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    scroll-behavior="elevate"
    scroll-target=".example-scroll-behavior-elevate"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

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

原始碼

範例：捲動時收合

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    variant="medium"
    scroll-behavior="shrink"
    scroll-threshold="30"
    scroll-target=".example-scroll-behavior-shrink"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

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

原始碼

範例：捲動時收合及加入陰影

Title

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    variant="medium"
    scroll-behavior="shrink elevate"
    scroll-target=".example-scroll-behavior-shrink-elevate"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>Title</mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

  <div class="example-scroll-behavior-shrink-elevate" style="height: 160px;overflow: auto;">
    <div style="height: 1000px"></div>
  </div>
</div>

原始碼

展開狀態的文字

對於 variant 屬性為 medium 或 large，且 scroll-behavior 屬性為 shrink 的頂部應用程式列，你可以在 <mdui-top-app-bar-title> 元件中加入 label-large slot，以設定展開狀態下顯示的文字。

這是收合狀態的標題這是展開狀態的標題

<div style="position: relative;overflow: hidden">
  <mdui-top-app-bar
    variant="medium"
    scroll-behavior="shrink elevate"
    scroll-target=".example-label-large-slot"
  >
    <mdui-button-icon icon="menu"></mdui-button-icon>
    <mdui-top-app-bar-title>
      這是收合狀態的標題
      <span slot="label-large">這是展開狀態的標題</span>
    </mdui-top-app-bar-title>
    <div style="flex-grow: 1"></div>
    <mdui-button-icon icon="more_vert"></mdui-button-icon>
  </mdui-top-app-bar>

  <div class="example-label-large-slot" style="height: 160px;overflow: auto;">
    <div style="height: 1000px"></div>
  </div>
</div>

原始碼

`mdui-top-app-bar-title` API

Slots

名稱
預設
頂部應用程式列的標題文字
`label-large`
展開狀態下的標題文字

CSS Parts

名稱
`label`
標題文字
`label-large`
展開狀態下的標題文字

`mdui-top-app-bar` API

屬性

HTML 屬性	JavaScript 屬性	型別	預設值
`variant`	`variant`	`'center-aligned' \| 'small' \| 'medium' \| 'large'`	`'small'`
頂部應用程式列的形狀。預設為 `small`。可選值包括： `center-aligned`：小型應用程式列，標題置中 `small`：小型應用程式列 `medium`：中型應用程式列 `large`：大型應用程式列
`hide`	`hide`	`boolean`	`false`
是否隱藏
`shrink`	`shrink`	`boolean`	`false`
是否縮小為 `variant="small"` 的樣式，僅在 `variant="medium"` 或 `variant="large"` 時生效
`scroll-behavior`	`scrollBehavior`	`'hide' \| 'shrink' \| 'elevate'`	-
捲動行為。可同時使用多個值，用空格分隔。可選值包括： `hide`：捲動時隱藏 `shrink`：在中型、大型應用程式列中可使用，捲動時縮小成小型應用程式列的樣式 `elevate`：捲動時新增陰影
`scroll-target`	`scrollTarget`	`string \| HTMLElement \| JQ<HTMLElement>`	-
需要監聽捲動事件的目標元素。值可以是 CSS 選擇器、DOM 元素、或 JQ 物件。預設監聽 `window` 的捲動事件
`scroll-threshold`	`scrollThreshold`	`number`	-
觸發捲動行為所需的捲動距離，單位為 `px`
`order`	`order`	`number`	-
該元件在 `<mdui-layout>` 中的版面順序，按從小到大排序。預設為 `0`

事件

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

Slots

名稱
預設
頂部應用程式列內部的元素

CSS 自訂屬性

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

Tooltip 工具提示

jq 工具庫