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` 值

BottomAppBar 底部应用栏

Layout 布局