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 定位:

  1. 当指定了 scroll-target 属性时。此时会在 scroll-target 的元素上添加 padding-top 样式。
  2. 当位于 <mdui-layout></mdui-layout> 组件中时。此时不会添加 padding-top 样式。

示例

位于指定容器内

默认情况下,顶部应用栏会相对于当前窗口,在页面顶部显示。

如果你希望将顶部应用栏放在指定的容器内,可以在 <mdui-top-app-bar> 组件上指定 scroll-target 属性,其值为可滚动内容的容器的 CSS 选择器或 DOM 元素。此时,顶部应用栏会相对于父元素显示(你需要自行在父元素上添加样式 position: relative; overflow: hidden)。

形状

可以通过在 <mdui-top-app-bar> 组件上使用 variant 属性来设置顶部应用栏的形状。

页面滚动时的行为

通过在 <mdui-top-app-bar> 组件上设置 scroll-behavior 属性,可以定义页面滚动时顶部应用栏的行为。可以同时设置多个行为,用空格分隔即可。

滚动行为包括:

  • hide:页面向下滚动时隐藏顶部应用栏,向上滚动时显示顶部应用栏。
  • shrink:仅在 variant 属性为 mediumlarge 时有效。页面向下滚动时展开顶部应用栏,向上滚动时收缩顶部应用栏。
  • elevate:页面向下滚动时,在顶部应用栏上添加阴影;页面滚回到顶部时,取消阴影。

使用 scroll-threshold 属性,可以设置滚动多少像素后开始触发顶部应用栏的滚动行为。(注意,为了响应及时,在使用了 elevate 滚动行为时,请不要再设置 scroll-threshold 属性。)

示例:滚动时隐藏

示例:滚动时添加阴影

示例:滚动时收缩

示例:滚动时收缩及添加阴影

展开状态的文本

对于 variant 属性为 mediumlarge,且 scroll-behavior 属性为 shrink 的顶部应用栏,你可以在 <mdui-top-app-bar-title> 组件中添加 label-large slot,以设置展开状态下的文本。

mdui-top-app-bar API

属性

HTML 属性JavaScript 属性Reflect类型默认值
variantvariant'center-aligned' | 'small' | 'medium' | 'large''small'

顶部应用栏的形状。默认为 small。可选值包括:

  • center-aligned:小型应用栏,标题居中
  • small:小型应用栏
  • medium:中型应用栏
  • large:大型应用栏
hidehidebooleanfalse

是否隐藏

shrinkshrinkbooleanfalse

是否缩小为 variant="small" 的样式,仅在 variant="medium"variant="large" 时生效

scroll-behaviorscrollBehavior'hide' | 'shrink' | 'elevate'-

滚动行为。可同时使用多个值,用空格分隔。可选值包括:

  • hide:滚动时隐藏
  • shrink:在中型、大型应用栏中可使用,滚动时缩小成小型应用栏的样式
  • elevate:滚动时添加阴影
scroll-targetscrollTargetstring | HTMLElement | JQ<HTMLElement>-

需要监听其滚动事件的元素。值可以是 CSS 选择器、DOM 元素、或 JQ 对象。默认监听 window 的滚动事件

scroll-thresholdscrollThresholdnumber-

在滚动多少距离之后触发滚动行为,单位为 px

orderordernumber-

该组件在 <mdui-layout> 中的布局顺序,按从小到大排序。默认为 0

事件

名称
show

开始显示时,事件被触发。可以通过调用 event.preventDefault() 阻止显示

shown

显示动画完成时,事件被触发

hide

开始隐藏时,事件被触发。可以通过调用 event.preventDefault() 阻止隐藏

hidden

隐藏动画完成时,事件被触发

Slots

名称
默认

顶部应用栏内部的元素

CSS 自定义属性

名称
--shape-corner

组件的圆角大小。可以指定一个具体的像素值;但更推荐引用设计令牌

--z-index

组件的 CSS z-index

mdui-top-app-bar-title API

Slots

名称
默认

顶部应用栏的标题文本

label-large

展开状态下的标题文本

CSS Parts

名称
label

标题文本

label-large

展开状态下的标题文本

MDUI文档English简体中文亮色模式暗色模式跟随系统
预设颜色
自选颜色
从壁纸提取颜色
请选择一张壁纸
开发指南
概述 安装 快速入门 TypeScript 支持 IDE 支持 本地化 常见问题
样式
暗色模式 动态配色 文章排版 设计令牌
与框架集成
React Vue Angular
组件
Button 按钮ButtonIcon 图标按钮Fab 浮动操作按钮SegmentedButton 分段按钮Chip 纸片Card 卡片Checkbox 复选框Radio 单选框Switch 开关切换Slider 滑块RangeSlider 范围滑块List 列表Collapse 折叠面板Tabs 选项卡Dropdown 下拉组件Menu 菜单Select 选择框TextField 文本框LinearProgress 线性进度指示器CircularProgress 圆形进度指示器Dialog 对话框Divider 分割线Avatar 头像Badge 徽标Icon 图标Tooltip 工具提示Snackbar 消息条NavigationBar 底部导航栏NavigationDrawer 侧边抽屉栏NavigationRail 侧边导航栏BottomAppBar 底部应用栏TopAppBar 顶部应用栏Layout 布局
工具函数
jq 工具库 dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
独立包
@mdui/icons 图标组件库