VuePress側邊欄配置與useSidebar的使用方式

更新時間：2025年06月16日 09:47:43 作者：紅衣大叔

這篇文章主要介紹了VuePress側邊欄配置與useSidebar的使用方式,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教

VuePress側邊欄配置與useSidebar的使用

在VuePress中，側邊欄（Sidebar）是一個重要的組成部分，用于組織文檔結構，提供給用戶方便的導航體驗。

本文將詳細介紹如何配置側邊欄，并介紹如何使用 useSidebar 組合式函數(shù)來操作側邊欄的狀態(tài)。

單一側邊欄的配置

最簡單的側邊欄配置方式是通過一個數(shù)組來定義導航結構。每個第一級的項目定義了一個“部分”（section），它應該包含一個文本標題（text）以及實際的導航鏈接（items）。

例如：

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Section Title A',
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' },
          // 更多子項...
        ]
      },
      {
        text: 'Section Title B',
        items: [
          { text: 'Item C', link: '/item-c' },
          { text: 'Item D', link: '/item-d' },
          // 更多子項...
        ]
      }
    ]
  }
}

每個鏈接應指定以 / 開頭的實際文件路徑。如果鏈接的末尾加上斜杠，則表示指向對應目錄下的 index.md 文件。

多個側邊欄的配置

你可以根據(jù)頁面路徑來顯示不同的側邊欄。例如，你可以為不同的文檔部分配置單獨的側邊欄。

首先按需組織Markdown文件：

.
├─ guide/
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ config/
   ├─ index.md
   ├─ three.md
   └─ four.md

然后更新配置文件以定義每個部分的側邊欄：

export default {
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          text: 'Guide',
          items: [
            { text: 'Index', link: '/guide/' },
            { text: 'One', link: '/guide/one' },
            { text: 'Two', link: '/guide/two' }
          ]
        }
      ],
      '/config/': [
        {
          text: 'Config',
          items: [
            { text: 'Index', link: '/config/' },
            { text: 'Three', link: '/config/three' },
            { text: 'Four', link: '/config/four' }
          ]
        }
      ]
    }
  }
}

可折疊的側邊欄組

在側邊欄中添加可折疊的功能，可以讓用戶通過點擊切換按鈕來隱藏或顯示某個部分的內(nèi)容。這有助于在內(nèi)容較多的情況下保持界面的整潔，并提供更好的用戶體驗。

要配置可折疊的側邊欄組，可以在定義側邊欄的配置中為每個部分添加一個 collapsed 屬性。

例如：

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Section Title A',
        collapsed: false, // 默認展開
        items: [
          { text: 'Item A', link: '/item-a' },
          { text: 'Item B', link: '/item-b' },
          // 更多子項...
        ]
      },
      {
        text: 'Section Title B',
        collapsed: true, // 默認收起
        items: [
          { text: 'Item C', link: '/item-c' },
          { text: 'Item D', link: '/item-d' },
          // 更多子項...
        ]
      }
    ]
  }
}

使用 useSidebar 組合式函數(shù)

useSidebar 是一個組合式函數(shù)，提供了與側邊欄相關數(shù)據(jù)的訪問。它返回一個包含多個響應式引用（Ref）和一些實用函數(shù)的對象。

export interface DocSidebar {
  isOpen: Ref<boolean>,
  sidebar: ComputedRef<DefaultTheme.SidebarItem[]>,
  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>,
  hasSidebar: ComputedRef<boolean>,
  hasAside: ComputedRef<boolean>,
  leftAside: ComputedRef<boolean>,
  isSidebarEnabled: ComputedRef<boolean>,
  open: () => void,
  close: () => void,
  toggle: () => void
}

使用 useSidebar 的示例如下：

<script setup>
import { useSidebar } from '@vuepress/theme-default';

const { hasSidebar } = useSidebar();
</script>

<template>
  <div v-if="hasSidebar">僅在存在側邊欄時顯示</div>
</template>

通過這種方式，你可以更靈活地管理和控制側邊欄的行為，以增強用戶體驗并使頁面布局更加動態(tài)和響應式。