跳至主要內容

导航栏

大约 7 分钟布局布局导航栏

导航栏可能包含你的站点名称、搜索框、 导航栏链接、多语言支持open in new window、仓库链接 和 外观弹窗。它们均取决于你的配置。

导航栏链接

你可以在主题选项中通过 navbar 配置导航栏链接，它接受一个数组。

字符串格式

配置导航栏最简单的方式，是依次填入需要展示的页面文件的路径，这样导航栏的文字、图标和链接会自动通过对应文件生成。

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: ["/zh/guide/README.md", "/zh/config/README.md", "/zh/faq.md"],
  }),
});

提示

你可以省略 .md 扩展名，以 / 结尾的路径会被推断为 /README.md。

对象格式

如果你对页面的图标不满意或者觉得页面标题太长，你可以改为配置一个对象。可用的配置项有:

  • text:: 项目文字
  • link: 项目链接
  • icon: 项目图标 (可选)
  • activeMatch: 项目激活匹配 (可选)，支持正则字符串。
// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: [
      {
        text: "指南",
        link: "/zh/guide/README.md",
        icon: "lightbulb",
        // 仅在 `/zh/guide/` 激活
        activeMatch: "^/zh/guide/$",
      },
      { text: "配置", link: "/zh/config/README.md", icon: "config" },
      {
        text: "常见问题",
        link: "/zh/faq.md",
        icon: "circle-question",
        // 会在 `/zh/faq` 开头的路径激活
        // 所以当你前往 `/zh/faq/xxx.html` 时也会激活
        activeMatch: "^/zh/faq",
      },
    ],
  }),
});

activeMatch 的高级用法

activeMatch 主要给予你控制路径是否激活的能力，比如你可能有如下链接:

  • /path/
  • /path/a/
  • /path/b/

此时你可能想避免在 /path/a/ 以及 /path/b/ 开头的路径下，出现两个菜单同时激活的情况。将第一项的 activeMatch 选项设置为 ^/path/(?:(?!a/|b/).*)?$ 就可以有效避免。

下拉列表

如果你需要展示较多的链接，你可以将同类链接整理成下拉列表。

你需要设置对象式导航栏配置项，并提供额外的 children 选项设置链接列表:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: [
      {
        text: "基础",
        icon: "circle-info",
        children: ["/zh/basic/markdown.md", "/zh/basic/vuepress.md"],
      },
    ],
  }),
});

由于大多数情况下，导航栏的分组项目都属于同一类别，会放在同一个子目录下，它们具有相同的路径前缀。

为了简化配置，你可以添加 prefix 字段为分组的每一个子链接添加一个前缀:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: [
      {
        text: "基础",
        icon: "circle-info",
        prefix: "/zh/basic/",
        children: ["markdown.md", "vuepress.md"],
      },
    ],
  }),
});

此外，你还可以通过嵌套的 children 来在下拉列表中设置分组:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: [
      {
        text: "插件列表",
        icon: "puzzle-piece",
        children: [
          {
            text: "内置插件",
            children: [
              /* 一些子项目 */
            ],
          },
          {
            text: "外部插件",
            children: [
              /* 一些子项目 */
            ],
          },
        ],
      },
    ],
  }),
});

禁用导航栏

你可以在主题选项中设置 navbar: false 来禁用所有页面的导航栏:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbar: false,
  }),
});

你也可以通过 YAML front matter 来禁用某个指定页面的导航栏:

---
navbar: false
---

禁用导航栏图标

你可以在主题选项中设置 navbarIcon: false 来禁用所有页面的导航栏图标:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbarIcon: false,
  }),
});

网站图标

你可以在主题选项中使用 logo 来配置站点的图标，请填入绝对路径。

注

请填写绝对路径并将 logo 放在 .vuepress/public 文件夹中。

配置图标后，图标将移动设备上取代先前的站点名称显示在导航栏上。

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    logo: "/logo.png",
  }),
});

提示

你可以在主题选项中设置 logoDark 以在深色模式下显示另一个 Logo。

多语言

主题的导航栏支持 多语言open in new window，所以你可以为每个语言单独设置上面提到的导航栏选项:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    locales: {
      "/": {
        logo: "/logo.svg",
        navbar: [
          /* 根目录下的英文配置 */
        ],
      },
      "/zh/": {
        logo: "/zh-logo.svg",
        navbar: [
          /* 中文目录下的中文配置 */
        ],
      },
    },
  }),
});

搜索框

vuepress-theme-hope 同默认主题一样，带来了搜索插件的内置支持。你可以根据自己的需要来自行添加插件并启用搜索功能。导航栏会自动出现对应的搜索框。

关于详情，详见 功能 → 搜索。

Git 仓库和编辑链接

当你在主题选项中提供了 repo 选项，将会自动在每个页面的导航栏生成源文件仓库按钮。

你可以在主题选项中通过 repoDisplay 控制是否显示仓库按钮。

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    // 默认为 GitHub. 同时也可以是一个完整的 URL
    repo: "vuepress-theme-hope/vuepress-theme-hope",
    // 自定义仓库链接文字。默认从 `repo` 中自动推断为
    // "GitHub" / "GitLab" / "Gitee" / "Bitbucket" 其中之一，或是 "Source"。
    repoLabel: "GitHub",
    // 是否在导航栏内显示仓库链接，默认为 `true`
    repoDisplay: true,
  }),
});

外观弹窗

提供下列三种功能:

布局配置

主题允许你自定义导航栏布局。 你可以在 navbarLayout 选项下的 start、center 和 end 键中添加组件。

可用组件:

  • Brand: 站点品牌
  • Links: 导航栏链接
  • Language: 语言切换菜单
  • Search: 搜索框
  • Outlook: 外观弹窗
  • Repo: 项目仓库

默认情况下，我们使用以下选项:

// .vuepress/config.ts
import { defineUserConfig } from "vuepress";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  theme: hopeTheme({
    navbarLayout: {
      start: ["Brand"],
      center: ["Links"],
      end: ["Language", "Repo", "Outlook", "Search"],
    },
  }),
});

相关助手与类型

vuepress-theme-hope 将导航栏的类型导出为 NavbarConfig，同时，提供了一个 navbar Helper 函数。它们可以在 TS 和 JS 中提供导航栏配置的校验与自动补全。

提示

它们主要应对当你将 VuePress 配置拆分成多个部分的情景。

// .vuepress/navbar.ts
import { navbar } from "vuepress-theme-hope";

export default navbar([
  /* 你的导航栏配置 */
]);

例子

本文档的导航栏配置
import { navbar } from "vuepress-theme-hope";


const linkHelper = getLinkHelper("/zh/");

export const zhNavbarConfig = navbar([
  "/zh/guide/",
  "/zh/config/",
  "/zh/faq/",
  {
    text: "教程",
    icon: "signs-post",
    prefix: "/zh/cookbook/",
    children: ["tutorial/", "markdown/", "vuepress/", "customize/"],
  },
  "/zh/migration/",
  {
    text: "项目",
    icon: "circle-info",
    prefix: "/zh/",
    children: [
      "changelog",
      "demo/",
      "contribution",
      {
        text: "插件",
        icon: "puzzle-piece",
        children: [
          {
            text: "自动目录插件",
            icon: "network-wired",
            link: linkHelper("auto-catalog"),
          },
          {
            text: "博客插件",
            icon: "blog",
            link: linkHelper("blog2"),
          },
          {
            text: "评论插件",
            icon: "comment",
            link: linkHelper("comment2"),
          },
          {
            text: "组件库",
            icon: "puzzle-piece",
            link: linkHelper("components"),
          },
          {
            text: "代码复制插件",
            icon: "copy",
            link: linkHelper("copy-code2"),
          },
          {
            text: "版权信息插件",
            icon: "copyright",
            link: linkHelper("copyright"),
          },
          {
            text: "Feed 插件",
            icon: "rss",
            link: linkHelper("feed2"),
          },
          {
            text: "LightGallery 插件",
            icon: "image",
            link: linkHelper("lightgallery"),
          },
          {
            text: "Markdown 增强插件",
            icon: "fab fa-markdown",
            link: linkHelper("md-enhance"),
          },
          {
            text: "图片预览插件",
            icon: "image",
            link: linkHelper("photo-swipe"),
          },
          {
            text: "PWA 插件",
            icon: "mobile",
            link: linkHelper("pwa2"),
          },
          {
            text: "阅读时间插件",
            icon: "book-open",
            link: linkHelper("reading-time2"),
          },
          {
            text: "移除 PWA 插件",
            icon: "trash-can",
            link: linkHelper("remove-pwa"),
          },
          {
            text: "重定向插件",
            icon: "fas fa-eject fa-rotate-90",
            link: linkHelper("redirect"),
          },
          {
            text: "Sass 调色板插件",
            icon: "palette",
            link: linkHelper("sass-palette"),
          },
          {
            text: "客户端搜索插件",
            icon: "search",
            link: linkHelper("search-pro"),
          },
          {
            text: "Seo 插件",
            icon: "wrench",
            link: linkHelper("seo2"),
          },
          {
            text: "VuePress 工具函数",
            icon: "toolbox",
            link: linkHelper("shared"),
          },
          {
            text: "Sitemap 插件",
            icon: "sitemap",
            link: linkHelper("sitemap2"),
          },
        ],
      },
    ],
  },
]);
MIT Licensed | Copyright © 2019-present Mr.Hope