NavigationRail 侧边导航栏

侧边导航栏为平板电脑和桌面电脑提供了访问不同主页面的方式。

使用方法

按需导入组件：

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

按需导入组件的 TypeScript 类型：

import type { NavigationRail } from 'mdui/components/navigation-rail.js';
import type { NavigationRailItem } from 'mdui/components/navigation-rail-item.js';

使用示例：（示例中的 style="position: relative" 是为了演示需要，实际使用时请移除该样式。）

Recent

Images

Library

<mdui-navigation-rail value="recent" style="position: relative">
  <mdui-navigation-rail-item icon="watch_later--outlined" value="recent">Recent</mdui-navigation-rail-item>
  <mdui-navigation-rail-item icon="image--outlined" value="images">Images</mdui-navigation-rail-item>
  <mdui-navigation-rail-item icon="library_music--outlined" value="library">Library</mdui-navigation-rail-item>
</mdui-navigation-rail>

注意事项：

该组件默认使用 position: fixed 定位，并会自动在 body 上添加 padding-left 或 padding-right 样式，以防止页面内容被该组件遮挡。

但在以下两种情况下，会默认使用 position: absolute 定位：

<mdui-navigation-rail> 组件的 contained 属性为 true 时。此时会在父元素上添加 padding-left 或 padding-right 样式。
当位于 <mdui-layout></mdui-layout> 组件中时。此时不会添加 padding-left 或 padding-right 样式。

样式

位于指定容器内

默认情况下，侧边导航栏会相对于当前窗口，在页面左侧或右侧显示。如果你希望将侧边导航栏放在指定的容器内，可以在 <mdui-navigation-rail> 组件上添加 contained 属性，此时侧边导航栏会相对于其父元素显示（你需要自行在父元素上添加 position: relative 样式）。

Recent

Images

Library

页面内容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">页面内容</div>
  </div>
</div>

源码

位于右侧

在 <mdui-navigation-rail> 组件上设置 placement 属性为 right，可以将侧边导航栏显示在右侧。

Recent

Images

Library

页面内容

<div style="position: relative">
  <mdui-navigation-rail placement="right" contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">页面内容</div>
  </div>
</div>

源码

显示分割线

在 <mdui-navigation-rail> 组件上添加 divider 属性，可以在侧边导航栏上添加一条分割线，以便和页面内容区分开。

Recent

Images

Library

页面内容

<div style="position: relative">
  <mdui-navigation-rail divider contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">页面内容</div>
  </div>
</div>

源码

在顶部/底部添加元素

可以在 <mdui-navigation-rail> 组件内通过 top、bottom slot 在顶部和底部添加元素。

Recent

Images

Library

页面内容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-button-icon icon="menu" slot="top"></mdui-button-icon>
    <mdui-fab lowered icon="edit--outlined" slot="top"></mdui-fab>
    <mdui-button-icon icon="settings" slot="bottom"></mdui-button-icon>

    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 600px;overflow: auto">
    <div style="height: 1000px">页面内容</div>
  </div>
</div>

源码

导航项垂直对齐方式

通过设置 <mdui-navigation-rail> 组件的 alignment 属性，可以修改导航项的垂直对齐方式。

Recent

Images

Library

start

center

end

<div class="example-alignment" style="position: relative">
  <mdui-navigation-rail alignment="start" contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 360px;overflow: auto">
    <mdui-segmented-button-group value="start" selects="single">
      <mdui-segmented-button value="start">start</mdui-segmented-button>
      <mdui-segmented-button value="center">center</mdui-segmented-button>
      <mdui-segmented-button value="end">end</mdui-segmented-button>
    </mdui-segmented-button-group>
  </div>
</div>

<script>
  const example = document.querySelector(".example-alignment");
  const navigationRail = example.querySelector("mdui-navigation-rail");
  const segmentedButtonGroup = example.querySelector("mdui-segmented-button-group");

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

源码

图标

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

Recent

Images

Library

页面内容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined" active-icon="image--filled">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item>
      Library
      <mdui-icon slot="icon" name="library_music--outlined"></mdui-icon>
      <mdui-icon slot="active-icon" name="library_music--filled"></mdui-icon>
    </mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">页面内容</div>
  </div>
</div>

源码

仅使用图标

<mdui-navigation-rail-item> 组件可以仅使用图标，不添加文本。

页面内容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-navigation-rail-item icon="watch_later--outlined"></mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined"></mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined"></mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">页面内容</div>
  </div>
</div>

源码

链接

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

Recent

Images

Library

页面内容

<div style="position: relative">
  <mdui-navigation-rail divider contained>
    <mdui-navigation-rail-item
      href="https://www.mdui.org"
      target="_blank"
      icon="watch_later--outlined"
    >Recent</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">页面内容</div>
  </div>
</div>

源码

徽标

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

Recent 99+

Images

Library

页面内容

<div style="position: relative">
  <mdui-navigation-rail contained>
    <mdui-navigation-rail-item icon="watch_later--outlined">
      Recent
      <mdui-badge slot="badge">99+</mdui-badge>
    </mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="image--outlined">Images</mdui-navigation-rail-item>
    <mdui-navigation-rail-item icon="library_music--outlined">Library</mdui-navigation-rail-item>
  </mdui-navigation-rail>

  <div style="height: 260px;overflow: auto">
    <div style="height: 1000px">页面内容</div>
  </div>
</div>

源码

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 属性	类型	默认值
`value`	`value`	`string`	-
当前选中的 `<mdui-navigation-rail-item>` 的值
`placement`	`placement`	`'left' \| 'right'`	`'left'`
导航栏的位置。可选值包括： `left`：左侧 `right`：右侧
`alignment`	`alignment`	`'start' \| 'center' \| 'end'`	`'start'`
`<mdui-navigation-rail-item>` 元素的对齐方式。可选值包括： `start`：顶部对齐 `center`：居中对齐 `end`：底部对齐
`contained`	`contained`	`boolean`	`false`
默认情况下，导航栏相对于 `body` 元素显示。当该参数设置为 `true` 时，导航栏将相对于其父元素显示。 Note：设置该属性时，必须在父元素上手动设置样式 `position: relative;`。
`divider`	`divider`	`boolean`	`false`
是否在导航栏和页面内容之间添加分割线
`order`	`order`	`number`	-
该组件在 `<mdui-layout>` 中的布局顺序，按从小到大排序。默认为 `0`

名称
`change`
值变化时触发

名称
默认
`<mdui-navigation-rail-item>` 组件
`top`
顶部的元素
`bottom`
底部的元素

名称
`top`
顶部元素的容器
`bottom`
底部元素的容器
`items`
`<mdui-navigation-rail-item>` 组件的容器

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

NavigationDrawer 侧边抽屉栏

BottomAppBar 底部应用栏

NavigationRail 侧边导航栏

使用方法

样式

位于指定容器内

位于右侧

显示分割线

在顶部/底部添加元素

导航项垂直对齐方式

图标

仅使用图标

链接

徽标

`mdui-navigation-rail-item` API

属性

方法

事件

Slots

CSS Parts

CSS 自定义属性

`mdui-navigation-rail` API

属性

事件

Slots

CSS Parts

CSS 自定义属性