NavigationBar 底部导航栏

导航栏用于在移动端页面中方便地在几个主要页面之间进行切换。

使用方法

按需导入组件：

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

按需导入组件的 TypeScript 类型：

import type { NavigationBar } from 'mdui/components/navigation-bar.js';
import type { NavigationBarItem } from 'mdui/components/navigation-bar-item.js';

使用示例：（示例中的 style="position: relative" 仅用于演示，实际使用时请移除该样式。）

Item 1

Item 2

Item 3

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
</mdui-navigation-bar>

注意事项：

该组件默认使用 position: fixed 定位，并会自动在 body 上添加 padding-bottom 样式，以防止页面内容被组件遮挡。但在以下两种情况下，会默认使用 position: absolute 定位：

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

示例

文本标签显示状态

导航栏中的文本标签默认在导航项小于等于 3 个时始终显示；当导航项大于 3 个时，仅显示选中状态的文本。

Item 1

Item 2

Item 3

Item 1

Item 2

Item 3

Item 4

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
</mdui-navigation-bar>

<br/>

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="directions_railway" value="item-3">Item 3</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-4">Item 4</mdui-navigation-bar-item>
</mdui-navigation-bar>

源码

你可以通过在 <mdui-navigation-bar> 组件上设置 label-visibility 属性来调整文本标签的显示状态。可选值有：

selected：仅显示选中状态的文本
labeled：始终显示文本
unlabeled：始终不显示文本

Item 1

Item 2

Item 3

selected

labeled

unlabeled

<mdui-navigation-bar value="item-1" label-visibility="selected" style="position: relative" class="example-label">
  <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
</mdui-navigation-bar>

<mdui-segmented-button-group value="selected" selects="single" style="margin-top: 16px">
  <mdui-segmented-button value="selected">selected</mdui-segmented-button>
  <mdui-segmented-button value="labeled">labeled</mdui-segmented-button>
  <mdui-segmented-button value="unlabeled">unlabeled</mdui-segmented-button>
</mdui-segmented-button-group>

<script>
  const navigationBar = document.querySelector(".example-label");
  const segmentedButtonGroup = navigationBar.nextElementSibling;

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

源码

位于指定容器内

默认情况下，导航栏会相对于当前窗口，在页面底部显示。

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

Item 1

Item 2

Item 3

页面内容

<div style="position: relative;overflow: hidden">
  <mdui-navigation-bar scroll-target=".example-scroll-target" value="item-1">
    <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
  </mdui-navigation-bar>

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

源码

滚动时隐藏

通过在 <mdui-navigation-bar> 组件上设置 scroll-behavior 属性为 hide，可以实现页面向下滚动时隐藏导航栏，向上滚动时显示导航栏的效果。

使用 scroll-threshold 属性，可以设置滚动多少像素后开始隐藏导航栏。

Item 1

Item 2

Item 3

页面内容

<div style="position: relative;overflow: hidden">
  <mdui-navigation-bar
    scroll-behavior="hide"
    scroll-threshold="30"
    scroll-target=".example-scroll-behavior"
    value="item-1"
  >
    <mdui-navigation-bar-item icon="place" value="item-1">Item 1</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
    <mdui-navigation-bar-item icon="people" value="item-3">Item 3</mdui-navigation-bar-item>
  </mdui-navigation-bar>

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

源码

图标

在 <mdui-navigation-bar-item> 组件上，icon 属性用于设置未激活状态的导航项图标，active-icon 属性用于设置激活状态的导航项图标。也可以通过 icon 和 active-icon slot 来设置未激活和激活状态的图标元素。

Item 1

Item 2

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item
    icon="place--outlined"
    active-icon="place"
    value="item-1"
  >Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item value="item-2">
    Item 2
    <mdui-icon slot="icon" name="people--outlined"></mdui-icon>
    <mdui-icon slot="active-icon" name="people"></mdui-icon>
  </mdui-navigation-bar-item>
</mdui-navigation-bar>

源码

链接

在 <mdui-navigation-bar-item> 组件上设置 href 属性，可以将导航项变为链接。此时，还可以使用与链接相关的属性：download、target、rel。

Item 1

Item 2

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" href="https://www.mdui.org" target="_blank" value="item-1">Item 1</mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
</mdui-navigation-bar>

源码

徽标

在 <mdui-navigation-bar-item> 组件中，可以通过 badge slot 添加徽章。

Item 1 99+

Item 2

<mdui-navigation-bar value="item-1" style="position: relative">
  <mdui-navigation-bar-item icon="place" value="item-1">
    Item 1
    <mdui-badge slot="badge">99+</mdui-badge>
  </mdui-navigation-bar-item>
  <mdui-navigation-bar-item icon="commute" value="item-2">Item 2</mdui-navigation-bar-item>
</mdui-navigation-bar>

源码

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 属性	类型	默认值
`hide`	`hide`	`boolean`	`false`
是否隐藏
`label-visibility`	`labelVisibility`	`'auto' \| 'selected' \| 'labeled' \| 'unlabeled'`	`'auto'`
文本的可视状态。可选值包括： `auto`：当选项小于等于3个时，始终显示文本；当选项大于3个时，仅显示选中状态的文本 `selected`：仅在选中状态显示文本 `labeled`：始终显示文本 `unlabeled`：始终不显示文本
`value`	`value`	`string`	-
当前选中的 `<mdui-navigation-bar-item>` 的值
`scroll-behavior`	`scrollBehavior`	`'hide' \| 'shrink' \| 'elevate'`	-
滚动行为。可选值包括： `hide`：滚动时隐藏
`scroll-target`	`scrollTarget`	`string \| HTMLElement \| JQ<HTMLElement>`	-
需要监听其滚动事件的元素。值可以是 CSS 选择器、DOM 元素、或 JQ 对象。默认监听 `window` 的滚动事件
`scroll-threshold`	`scrollThreshold`	`number`	-
在滚动多少距离之后触发滚动行为，单位为 `px`
`order`	`order`	`number`	-
该组件在 `<mdui-layout>` 中的布局顺序，按从小到大排序。默认为 `0`

名称
`change`
值变化时触发
`show`
开始显示时，事件被触发。可以通过调用 `event.preventDefault()` 阻止显示
`shown`
显示动画完成时，事件被触发
`hide`
开始隐藏时，事件被触发。可以通过调用 `event.preventDefault()` 阻止隐藏
`hidden`
隐藏动画完成时，事件被触发

名称
默认
`<mdui-navigation-bar-item>` 组件

名称
`--shape-corner`
组件的圆角大小。可以指定一个具体的像素值；但更推荐引用设计令牌
`--z-index`
组件的 CSS `z-index` 值

Menu 菜单

NavigationDrawer 侧边抽屉栏

NavigationBar 底部导航栏

使用方法

示例

文本标签显示状态

位于指定容器内

滚动时隐藏

图标

链接

徽标

`mdui-navigation-bar-item` API

属性

方法

事件

Slots

CSS Parts

CSS 自定义属性

`mdui-navigation-bar` API

属性

事件

Slots

CSS 自定义属性