跳到主要内容
输入关键词开始搜索，↑ ↓ 选择，Enter 打开
没有找到匹配的文档

导航溢出

当空间有限时，使用 Priority+ 模式将导航项自动折叠到“更多”菜单中。

层级：components
查看原文
本页目录

它是如何工作的

导航溢出组件（也称为“Priority+”模式）会自动检测导航项是否无法适应其容器，并将它们移动到菜单中。这提供了一种响应式导航体验，而无需为不同的屏幕尺寸使用不同的标记。

在开始之前，你需要了解以下内容：

  • 将你的.nav包裹在.nav-overflow元素中，并在该包装器上添加data-bs-toggle="nav-overflow"。
  • 响应容器大小，而不是视口大小。组件通过 ResizeObserver 监视包装器，因此它可以在嵌入环境、文档示例和响应式容器中工作。
  • 包装器是确保可靠性的关键。折叠项会改变导航的宽度，因此组件改为测量包装器。测量导航会将结果反馈回作为输入。
  • 溢出项会被克隆到“更多”菜单中，同时原始项被隐藏。托管菜单的导航项是个例外：其.menu会移动到溢出菜单的子菜单中。
  • 适用于所有导航样式：默认、胶囊、标签和下划线。
  • 溢出菜单中会保留活动和禁用状态。

此组件的动画效果取决于 prefers-reduced-motion 媒体查询。请参阅我们无障碍文档中的 减少动画部分。

示例

将导航包裹在<div class="nav-overflow" data-bs-toggle="nav-overflow">中。当项目放不下时，它们会自动移动到“更多”菜单中。拖动下面容器的右边缘可以查看当空间有限时，导航项目如何自动移动到“更多”菜单。

HTML
<div class="nav-overflow" data-bs-toggle="nav-overflow">
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link active" aria-current="page" href="#">Home</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Dashboard</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Products</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Services</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Analytics</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Reports</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Settings</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Help</a>
    </li>
  </ul>
</div>

带标签页

溢出模式与标签导航完美配合：

HTML
<div class="nav-overflow" data-bs-toggle="nav-overflow">
  <ul class="nav nav-tabs">
    <li class="nav-item">
      <a class="nav-link active" aria-current="page" href="#">Overview</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Details</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">History</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Activity</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Comments</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Attachments</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Related</a>
    </li>
  </ul>
</div>

带下划线

HTML
<div class="nav-overflow" data-bs-toggle="nav-overflow">
  <ul class="nav nav-underline">
    <li class="nav-item">
      <a class="nav-link active" aria-current="page" href="#">Home</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Features</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Pricing</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">FAQs</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">About</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Contact</a>
    </li>
  </ul>
</div>

保持物品可见

在不应移至溢出菜单的项目上使用 .nav-overflow-keep 类。这些项目将始终可见，无论可用空间如何——对“主页”或操作按钮等高优先级项目特别有用。

HTML
<div class="nav-overflow" data-bs-toggle="nav-overflow">
  <ul class="nav nav-pills">
    <li class="nav-item nav-overflow-keep">
      <a class="nav-link active" aria-current="page" href="#">Home</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Products</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Services</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">About</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Blog</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Careers</a>
    </li>
    <li class="nav-item nav-overflow-keep">
      <a class="nav-link" href="#">Contact</a>
    </li>
  </ul>
</div>

带有禁用项目

当项目移动到溢出菜单时，禁用状态会被保留：

HTML
<div class="nav-overflow" data-bs-toggle="nav-overflow">
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link active" aria-current="page" href="#">Active</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Link</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Another link</a>
    </li>
    <li class="nav-item">
      <a class="nav-link disabled" aria-disabled="true">Disabled</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">More content</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Even more</a>
    </li>
  </ul>
</div>

在导航栏中

导航溢出模式也可以在 导航栏 内使用，用于适应可用空间的水平导航：

HTML
<nav class="navbar navbar-expand bg-1">
  <div class="container-fluid">
    <a class="navbar-brand" href="#">Brand</a>
    <div class="nav-overflow" data-bs-toggle="nav-overflow">
      <ul class="nav navbar-nav">
        <li class="nav-item">
          <a class="nav-link active" aria-current="page" href="#">Home</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Features</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Pricing</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">About</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#">Contact</a>
        </li>
      </ul>
    </div>
  </div>
</nav>

带菜单

一个已经包含菜单的导航项会成为溢出菜单的子菜单。该插件会移动原始 .menu 而不是克隆它，因此嵌套子菜单保持完整。

HTML
<div class="nav-overflow" data-bs-toggle="nav-overflow">
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link active" aria-current="page" href="#">Home</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Dashboard</a>
    </li>
    <li class="nav-item">
      <button class="nav-link" type="button" data-bs-toggle="menu" aria-expanded="false">
        Products
      </button>
      <div class="menu">
        <a class="menu-item" href="#">Laptops</a>
        <div class="submenu">
          <button class="menu-item" type="button">Phones</button>
          <div class="menu">
            <a class="menu-item" href="#">iPhone</a>
            <a class="menu-item" href="#">Android</a>
          </div>
        </div>
        <a class="menu-item" href="#">Tablets</a>
      </div>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Services</a>
    </li>
    <li class="nav-item">
      <button class="nav-link" type="button" data-bs-toggle="menu" aria-expanded="false">
        Company
      </button>
      <div class="menu">
        <a class="menu-item" href="#">About</a>
        <a class="menu-item" href="#">Careers</a>
        <a class="menu-item" href="#">Press</a>
      </div>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Analytics</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Reports</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#">Help</a>
    </li>
  </ul>
</div>

自定义切换

自定义文本

使用 moreText 选项来自定义溢出切换按钮中显示的文本：

JavaScript
          const wrapper = document.querySelector('.nav-overflow')
new bootstrap.NavOverflow(wrapper, {
  moreText: 'See all'
})

自定义图标

通过 moreIcon 选项提供自定义图标。任何 HTML 字符串都可以，包括内联 SVG：

JavaScript
          const wrapper = document.querySelector('.nav-overflow')
new bootstrap.NavOverflow(wrapper, {
  moreIcon: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M3 9.5a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3m5 0a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3m5 0a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3"/></svg>',
  moreText: false // Icon only
})

将 moreText 设置为 false 以创建仅图标切换。组件随后不会写入 .nav-overflow-text 元素，并将按钮标注为 aria-label="More"，以便它仍然有名称。空字符串效果相同。若要将按钮命名为其他名称，请编写你自己的切换：

HTML
          <div class="nav-overflow" data-bs-toggle="nav-overflow">
  <ul class="nav nav-pills">
    <li class="nav-item"><a class="nav-link" href="#">Link 1</a></li>
    <li class="nav-item nav-overflow-item">
      <button class="nav-link nav-overflow-toggle" type="button" data-bs-toggle="menu" aria-label="Show more links">
        <span class="nav-overflow-icon">…</span>
      </button>
      <div class="nav-overflow-menu menu"></div>
    </li>
  </ul>
</div>

或者，将一个带有 data-bs-overflow-icon 的元素放置在包装器内，紧挨着导航栏。组件会拾取它，将其用作切换图标，并从 DOM 中移除原始元素。此选项优先于 moreIcon 选项。

HTML
          <div class="nav-overflow" data-bs-toggle="nav-overflow">
  <ul class="nav nav-pills">
    <li class="nav-item"><a class="nav-link" href="#">Link 1</a></li>
    <li class="nav-item"><a class="nav-link" href="#">Link 2</a></li>
  </ul>
  <svg data-bs-overflow-icon xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
    <path d="M8 4.754a3.246 3.246 0 1 0 0 6.492 3.246 3.246 0 0 0 0-6.492"/>
  </svg>
</div>

图标位置

使用 iconPlacement 选项将图标放置在文本之前（'start'，默认）或之后（'end'）：

JavaScript
          const wrapper = document.querySelector('.nav-overflow')
new bootstrap.NavOverflow(wrapper, {
  moreText: 'Menu',
  iconPlacement: 'end'
})

最少可见项目

使用 threshold 选项以确保在溢出生效之前至少有一定数量的项目保持可见：

JavaScript
          const wrapper = document.querySelector('.nav-overflow')
new bootstrap.NavOverflow(wrapper, {
  threshold: 3 // Always keep at least 3 items visible
})

全部折叠

当包装器的宽度低于阈值时，使用 collapseBelow 选项将所有项强制放入溢出下拉菜单。传递一个断点名称以从 --bs-breakpoint-{name} 中解析值，或传递一个数字以获得直接的像素值。

HTML
          <div class="nav-overflow" data-bs-toggle="nav-overflow" data-bs-collapse-below="md">
  <ul class="nav nav-pills">
    <li class="nav-item"><a class="nav-link" href="#">Link 1</a></li>
    <li class="nav-item"><a class="nav-link" href="#">Link 2</a></li>
    <li class="nav-item"><a class="nav-link" href="#">Link 3</a></li>
  </ul>
</div>

或者通过 JavaScript 使用原始像素值：

JavaScript
          const wrapper = document.querySelector('.nav-overflow')
new bootstrap.NavOverflow(wrapper, {
  collapseBelow: 768
})

超过阈值后，正常的渐进性坍塌恢复。标记为.nav-overflow-keep的项目永远不会坍塌。

用法

通过数据属性

添加 data-bs-toggle="nav-overflow" 到 .nav-overflow 用于自动启用溢出行为的封装器。

属性描述
data-bs-toggle="nav-overflow"启用包装内 .nav 的响应式溢出处理。
HTML
          <div class="nav-overflow" data-bs-toggle="nav-overflow">
  <ul class="nav nav-pills">
    <li class="nav-item"><a class="nav-link" href="#">Link 1</a></li>
    <li class="nav-item"><a class="nav-link" href="#">Link 2</a></li>
    <li class="nav-item"><a class="nav-link" href="#">Link 3</a></li>
    <!-- More items... -->
  </ul>
</div>

通过 JavaScript

手动初始化导航溢出组件。传递包装器，而不是导航：

JavaScript
          const wrapperElement = document.querySelector('.nav-overflow')
const navOverflow = new bootstrap.NavOverflow(wrapperElement, {
  moreText: 'More',
  threshold: 2
})

依赖项

如果你从源代码构建 Bootstrap 的 JS，则 nav-overflow 插件需要以下 JavaScript 文件：

文件描述
js/src/nav-overflow.ts主导航溢出组件
js/src/base-component.ts基础组件类
js/src/menu.ts菜单组件
js/src/dom/data.ts元素数据存储
js/src/dom/event-handler.ts事件处理工具
js/src/dom/manipulator.ts数据属性操作
js/src/dom/selector-engine.tsDOM选择器工具
js/src/util/config.ts配置基类
js/src/util/floating-ui.ts响应式布局工具
js/src/util/index.ts核心实用功能
js/src/util/sanitizer.tsHTML 内容净化器
@floating-ui/dom第三方定位库

选项

由于选项可以通过数据属性或 JavaScript 传递，你可以将选项名称附加到 data-bs-，就像在 data-bs-animation="{value}" 中一样。确保在通过数据属性传递选项时，将选项名称的大小写类型从“camelCase”更改为“kebab-case”。例如，使用 data-bs-custom-class="beautifier" 而不是 data-bs-customClass="beautifier"。

所有组件都支持一个保留的数据属性 data-bs-config，该属性可以以 JSON 字符串的形式存放简单的组件配置。当一个元素具有 data-bs-config='{"delay":0, "title":123}' 和 data-bs-title="456" 属性时，最终的 title 值将是 456，并且单独的数据属性将覆盖在 data-bs-config 上给定的值。此外，现有的数据属性也可以存放像 data-bs-delay='{"show":0,"hide":150}' 这样的 JSON 值。

最终的配置对象是data-bs-config、data-bs-和js object合并的结果，其中最新提供的键值会覆盖其他键值。

名称类型默认描述
collapseBelownumber|string0包裹器宽度低于此宽度时，所有项目将折叠到溢出下拉菜单中。传递一个断点名称（例如， 'md') 来解决 --bs-breakpoint-{name}，或者一个直接的像素值数字。 0 禁用。
iconPlacementstring'start'切换按钮中图标相对于文本的位置。使用 'start' 在文本之前或 'end' 之后用
menuPlacementstring'bottom-end'溢出下拉菜单的位置，作为传入参数 data-bs-placement 到菜单切换。
menuStrategystring'absolute'传递的溢出菜单定位策略 data-bs-strategy 到菜单切换。使用 'fixed' 当一个溢出祖先会裁剪菜单时。
moreTextstring|boolean'More'溢出切换按钮的文本标签。以纯文本插入。使用 false （或空字符串）用于仅图标切换，该切换被标记 aria-label="More" 取而代之
moreIconstring'<svg>...</svg>'用于溢出切换按钮的 SVG 或 HTML 图标。通过 图标内容清理器 在插入之前。被子元素的覆盖 data-bs-overflow-icon 如果存在（也进行了消毒）。
thresholdnumber0在显示溢出之前保持可见的最少项目数。

方法

所有 API 方法都是异步的，并会启动一个过渡。 它们在过渡开始后会立即返回给调用者，但在过渡结束之前返回。此外，对正在过渡的组件的方法调用将被忽略。 在我们的 JavaScript 文档中了解更多信息。

你可以使用构造函数创建一个导航溢出实例：

JavaScript
          const navOverflow = new bootstrap.NavOverflow('#myNav', {
  threshold: 2
})
方法描述
dispose销毁导航溢出实例，并将项目恢复到原来的位置。
getInstance静态方法，用于获取与 DOM 元素关联的导航溢出实例。
getOrCreateInstance静态方法，用于获取导航溢出实例，如果未初始化则创建一个新的实例。
update手动重新计算哪些项目应该溢出。会在调整大小时自动调用。

事件

Bootstrap 的导航溢出组件提供了事件以连接到溢出功能。两个事件都会在 .nav-overflow 包装器上触发。

事件类型描述
update.bs.navoverflow在溢出计算更新时触发（在调整大小或手动更新时）。
overflow.bs.navoverflow当项目被移到溢出菜单时触发。事件包括overflowCount和visibleCount属性。
JavaScript
          const myNav = document.getElementById('myNav') // the .nav-overflow wrapper

myNav.addEventListener('overflow.bs.navoverflow', event => {
  console.log(`${event.overflowCount} items moved to overflow`)
  console.log(`${event.visibleCount} items still visible`)
})