VuePress側(cè)邊欄配置與useSidebar的使用方式

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

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

VuePress側(cè)邊欄配置與useSidebar的使用

在VuePress中，側(cè)邊欄（Sidebar）是一個(gè)重要的組成部分，用于組織文檔結(jié)構(gòu)，提供給用戶方便的導(dǎo)航體驗(yàn)。

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

單一側(cè)邊欄的配置

最簡(jiǎn)單的側(cè)邊欄配置方式是通過一個(gè)數(shù)組來(lái)定義導(dǎo)航結(jié)構(gòu)。每個(gè)第一級(jí)的項(xiàng)目定義了一個(gè)“部分”（section），它應(yīng)該包含一個(gè)文本標(biāo)題（text）以及實(shí)際的導(dǎo)航鏈接（items）。

例如：

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

每個(gè)鏈接應(yīng)指定以 / 開頭的實(shí)際文件路徑。如果鏈接的末尾加上斜杠，則表示指向?qū)?yīng)目錄下的 index.md 文件。

多個(gè)側(cè)邊欄的配置

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

首先按需組織Markdown文件：

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

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

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' }
          ]
        }
      ]
    }
  }
}

可折疊的側(cè)邊欄組

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

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

例如：

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

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

useSidebar 是一個(gè)組合式函數(shù)，提供了與側(cè)邊欄相關(guān)數(shù)據(jù)的訪問。它返回一個(gè)包含多個(gè)響應(yīng)式引用（Ref）和一些實(shí)用函數(shù)的對(duì)象。

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">僅在存在側(cè)邊欄時(shí)顯示</div>
</template>

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

總結(jié)

通過合理的側(cè)邊欄配置，可以顯著提升文檔的導(dǎo)航性和用戶體驗(yàn)。無(wú)論是單一的側(cè)邊欄還是根據(jù)不同路徑顯示的多個(gè)側(cè)邊欄，VuePress 都提供了豐富的配置選項(xiàng)。同時(shí)，useSidebar 組合式函數(shù)進(jìn)一步增強(qiáng)了側(cè)邊欄的交互性和動(dòng)態(tài)性。

以上為個(gè)人經(jīng)驗(yàn)，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。

您可能感興趣的文章: