仪表盘侧边栏

一个可调整大小和可折叠的侧边栏，用于在仪表盘中显示。

用法

DashboardSidebar 组件用于显示侧边栏。其状态（尺寸、折叠等）将根据你提供给 DashboardGroup 组件的 storage 和 storage-key 属性进行保存。

请在 DashboardGroup 组件的默认插槽中使用它。

layouts/dashboard.vue

<template>
  <UDashboardGroup>
    <UDashboardSidebar />

    <slot />
  </UDashboardGroup>
</template>

当使用 resizable 属性时，此组件没有单一的根元素，因此如果你使用了页面过渡或布局需要单一根元素，请将其包装在一个容器中（例如 <div class="flex flex-1">）。

使用 header、default 和 footer 插槽来自定义侧边栏，使用 body 或 content 插槽来自定义侧边栏菜单。

<script setup lang="ts">
import type { NavigationMenuItem } from '@nuxt/ui'

const items: NavigationMenuItem[][] = [[{
  label: 'Home',
  icon: 'i-lucide-house',
  active: true
}, {
  label: 'Inbox',
  icon: 'i-lucide-inbox',
  badge: '4'
}, {
  label: 'Contacts',
  icon: 'i-lucide-users'
}, {
  label: 'Settings',
  icon: 'i-lucide-settings',
  defaultOpen: true,
  children: [{
    label: 'General'
  }, {
    label: 'Members'
  }, {
    label: 'Notifications'
  }]
}], [{
  label: 'Feedback',
  icon: 'i-lucide-message-circle',
  to: 'https://github.com/nuxt-ui-templates/dashboard',
  target: '_blank'
}, {
  label: 'Help & Support',
  icon: 'i-lucide-info',
  to: 'https://github.com/nuxt/ui',
  target: '_blank'
}]]
</script>

<template>
  <UDashboardSidebar collapsible resizable :ui="{ footer: 'border-t border-default' }">
    <template #header="{ collapsed }">
      <Logo v-if="!collapsed" class="h-5 w-auto shrink-0" />
      <UIcon v-else name="i-simple-icons-nuxtdotjs" class="size-5 text-primary mx-auto" />
    </template>

    <template #default="{ collapsed }">
      <UButton
        :label="collapsed ? undefined : 'Search...'"
        icon="i-lucide-search"
        color="neutral"
        variant="outline"
        block
        :square="collapsed"
      >
        <template v-if="!collapsed" #trailing>
          <div class="flex items-center gap-0.5 ms-auto">
            <UKbd value="meta" variant="subtle" />
            <UKbd value="K" variant="subtle" />
          </div>
        </template>
      </UButton>

      <UNavigationMenu
        :collapsed="collapsed"
        :items="items[0]"
        orientation="vertical"
      />

      <UNavigationMenu
        :collapsed="collapsed"
        :items="items[1]"
        orientation="vertical"
        class="mt-auto"
      />
    </template>

    <template #footer="{ collapsed }">
      <UButton
        :avatar="{
          src: 'https://github.com/benjamincanac.png'
        }"
        :label="collapsed ? undefined : 'Benjamin'"
        color="neutral"
        variant="ghost"
        class="w-full"
        :block="collapsed"
      />
    </template>
  </UDashboardSidebar>
</template>

将侧边栏拖动到屏幕左侧边缘附近即可将其折叠。

可调节尺寸

使用 resizable 属性使侧边栏可以调节尺寸。

可调节尺寸 (resizable)

<template>
  <UDashboardSidebar resizable>
    <Placeholder class="h-96" />
  </UDashboardSidebar>
</template>

Collapsible

使用 collapsible 属性使侧边栏在拖动到屏幕边缘附近时可以折叠。

如果侧边栏不是 可折叠的 (collapsible)，则 DashboardSidebarCollapse 组件将不起作用。

collapsible

<template>
  <UDashboardSidebar resizable collapsible>
    <Placeholder class="h-96" />
  </UDashboardSidebar>
</template>

你可以访问插槽属性中的 collapsed 状态，以便在侧边栏折叠时自定义其内容。

尺寸

使用 min-size、max-size、default-size 和 collapsed-size 属性来自定义侧边栏的大小。

最小尺寸 (minSize)

默认尺寸 (defaultSize)

最大尺寸 (maxSize)

折叠后尺寸 (collapsedSize)

<template>
  <UDashboardSidebar
    resizable
    collapsible
    :min-size="22"
    :default-size="35"
    :max-size="40"
    :collapsed-size="0"
  >
    <Placeholder class="h-96" />
  </UDashboardSidebar>
</template>

默认情况下，尺寸按百分比计算。你可以通过 DashboardGroup 组件上的 unit 属性来更改此设置。

collapsed-size 属性默认设置为 0，但侧边栏具有 min-w-16 以确保其可见。

方向

使用 side 属性更改侧边栏的位置。默认为 left（左侧）。

side

<template>
  <UDashboardSidebar side="right" resizable collapsible>
    <Placeholder class="h-96" />
  </UDashboardSidebar>
</template>

模式

使用 mode 属性更改侧边栏菜单的模式。默认为 slideover。

使用 body 插槽填充菜单主体（页眉下方），或使用 content 插槽填充整个菜单。

你可以使用 menu 属性来自定义侧边栏的菜单，它会根据你选择的模式自动适应。

mode

<script setup lang="ts">
import type { NavigationMenuItem } from '@nuxt/ui'

defineProps<{
  mode: 'drawer' | 'slideover' | 'modal'
}>()

const items: NavigationMenuItem[] = [{
  label: 'Home',
  icon: 'i-lucide-house',
  active: true
}, {
  label: 'Inbox',
  icon: 'i-lucide-inbox'
}, {
  label: 'Contacts',
  icon: 'i-lucide-users'
}]
</script>

<template>
  <UDashboardGroup>
    <UDashboardSidebar :mode="mode">
      <template #header="{ collapsed }">
        <Logo v-if="!collapsed" class="h-5 w-auto" />
        <UIcon v-else name="i-simple-icons-nuxtdotjs" class="size-5 text-primary mx-auto" />
      </template>

      <UNavigationMenu
        :items="items"
        orientation="vertical"
      />
    </UDashboardSidebar>

    <UDashboardPanel>
      <template #header>
        <UDashboardNavbar title="Dashboard" />
      </template>
    </UDashboardPanel>
  </UDashboardGroup>
</template>

这些示例包含 DashboardGroup、DashboardPanel 和 DashboardNavbar 组件，因为它们是演示移动端侧边栏所必需的。

Toggle

使用 toggle 属性自定义在移动端显示的 DashboardSidebarToggle 组件。

您可以将 Button 组件的任何属性传递过来以进行自定义。

<script setup lang="ts">
import type { NavigationMenuItem } from '@nuxt/ui'

const items: NavigationMenuItem[] = [{
  label: 'Home',
  icon: 'i-lucide-house',
  active: true
}, {
  label: 'Inbox',
  icon: 'i-lucide-inbox'
}, {
  label: 'Contacts',
  icon: 'i-lucide-users'
}]
</script>

<template>
  <UDashboardGroup>
    <UDashboardSidebar
      open
      :toggle="{
        color: 'primary',
        variant: 'subtle',
        class: 'rounded-full'
      }"
    >
      <template #header>
        <Logo class="h-5 w-auto" />
      </template>

      <UNavigationMenu
        :items="items"
        orientation="vertical"
      />
    </UDashboardSidebar>

    <UDashboardPanel>
      <template #header>
        <UDashboardNavbar title="Dashboard" />
      </template>
    </UDashboardPanel>
  </UDashboardGroup>
</template>

切换侧边

使用 toggle-side 属性更改切换按钮的位置。默认为 left（左侧）。

<script setup lang="ts">
import type { NavigationMenuItem } from '@nuxt/ui'

const items: NavigationMenuItem[] = [{
  label: 'Home',
  icon: 'i-lucide-house',
  active: true
}, {
  label: 'Inbox',
  icon: 'i-lucide-inbox'
}, {
  label: 'Contacts',
  icon: 'i-lucide-users'
}]
</script>

<template>
  <UDashboardGroup>
    <UDashboardSidebar
      open
      toggle-side="right"
    >
      <template #header>
        <Logo class="h-5 w-auto" />
      </template>

      <UNavigationMenu
        :items="items"
        orientation="vertical"
      />
    </UDashboardSidebar>

    <UDashboardPanel>
      <template #header>
        <UDashboardNavbar title="Dashboard" />
      </template>
    </UDashboardPanel>
  </UDashboardGroup>
</template>

示例

控制打开状态

你可以通过使用 open 属性或 v-model:open 指令来控制打开状态。

<script setup lang="ts">
import type { NavigationMenuItem } from '@nuxt/ui'

const items: NavigationMenuItem[] = [{
  label: 'Home',
  icon: 'i-lucide-house',
  active: true
}, {
  label: 'Inbox',
  icon: 'i-lucide-inbox'
}, {
  label: 'Contacts',
  icon: 'i-lucide-users'
}]

const open = ref(true)

defineShortcuts({
  o: () => open.value = !open.value
})
</script>

<template>
  <UDashboardSidebar v-model:open="open">
    <template #header="{ collapsed }">
      <Logo v-if="!collapsed" class="h-5 w-auto" />
      <UIcon v-else name="i-simple-icons-nuxtdotjs" class="size-5 text-primary mx-auto" />
    </template>

    <UNavigationMenu
      :items="items"
      orientation="vertical"
    />
  </UDashboardSidebar>
</template>

在此示例中，利用 defineShortcuts，你可以通过按 O 键来切换 DashboardSidebar 的打开状态。

控制折叠状态

你可以通过使用 collapsed 属性或 v-model:collapsed 指令来控制折叠状态。

<script setup lang="ts">
import type { NavigationMenuItem } from '@nuxt/ui'

const items: NavigationMenuItem[] = [{
  label: 'Home',
  icon: 'i-lucide-house',
  active: true
}, {
  label: 'Inbox',
  icon: 'i-lucide-inbox'
}, {
  label: 'Contacts',
  icon: 'i-lucide-users'
}]

const collapsed = ref(false)

defineShortcuts({
  c: () => collapsed.value = !collapsed.value
})
</script>

<template>
  <UDashboardSidebar v-model:collapsed="collapsed" collapsible>
    <template #header>
      <Logo v-if="!collapsed" class="h-5 w-auto" />
      <UIcon v-else name="i-simple-icons-nuxtdotjs" class="size-5 text-primary mx-auto" />
    </template>

    <UNavigationMenu
      :collapsed="collapsed"
      :items="items"
      orientation="vertical"
    />
  </UDashboardSidebar>
</template>

在此示例中，利用 defineShortcuts，你可以通过按 C 键来切换 DashboardSidebar 的折叠状态。

API

属性

属性	默认值	类型
`mode`	`'slideover'`	`T` 侧边栏菜单的模式。
`菜单 (menu)`		`DashboardSidebarMenu<T>` 侧边栏菜单组件的属性。
`toggle`	`true`	`boolean \| Omit<ButtonProps, LinkPropsKeys>` 一个用于在移动设备上切换侧边栏的按钮。
`toggleSide`	`'left'`	`"left" \| "right"` 渲染切换按钮的侧边位置。
`自动关闭 (autoClose)`	`true`	`boolean` 当路由变化时自动关闭。
`id`	`useId()`	`string` 面板的 ID。
`side`	`'left'`	`"left" \| "right"` 渲染面板的一侧。
`最小尺寸 (minSize)`	`10`	`number` 面板的最小尺寸。
`最大尺寸 (maxSize)`	`20`	`number` 面板的最大尺寸。
`默认尺寸 (defaultSize)`	`15`	`number` 面板的默认尺寸。
`可调节尺寸 (resizable)`	`false`	`boolean` 是否允许用户调整面板尺寸。
`collapsible`	`false`	`boolean` 是否允许用户折叠面板。
`折叠后尺寸 (collapsedSize)`	`0`	`number` 折叠时面板的尺寸。
`open`	`false`	`boolean`
`collapsed`	`false`	`boolean`
`ui`		`{ root?: ClassNameValue; header?: ClassNameValue; body?: ClassNameValue; footer?: ClassNameValue; toggle?: ClassNameValue; handle?: ClassNameValue; content?: ClassNameValue; overlay?: ClassNameValue; }`

插槽

插槽	类型
`页头`	`{ collapsed?: boolean \| undefined; collapse?: ((value: boolean) => void) \| undefined; }`
`default`	`{ collapsed?: boolean \| undefined; collapse?: ((value: boolean) => void) \| undefined; }`
`页脚`	`{ collapsed?: boolean \| undefined; collapse?: ((value: boolean) => void) \| undefined; }`
`toggle`	`{ open: boolean; toggle: () => void; ui: object; }`
`内容`	`{ close?: (() => void) \| undefined; }`
`尺寸调节手柄 (resize-handle)`	`{ onMouseDown: (e: MouseEvent) => void; onTouchStart: (e: TouchEvent) => void; onDoubleClick: (e: MouseEvent) => void; ui: object; }`

主题

app.config.ts

export default defineAppConfig({
  ui: {
    dashboardSidebar: {
      slots: {
        root: 'relative hidden lg:flex flex-col min-h-svh min-w-16 w-(--width) shrink-0',
        header: 'h-(--ui-header-height) shrink-0 flex items-center gap-1.5 px-4',
        body: 'flex flex-col gap-4 flex-1 overflow-y-auto px-4 py-2',
        footer: 'shrink-0 flex items-center gap-1.5 px-4 py-2',
        toggle: '',
        handle: '',
        content: 'lg:hidden',
        overlay: 'lg:hidden'
      },
      variants: {
        menu: {
          true: {
            header: 'sm:px-6',
            body: 'sm:px-6',
            footer: 'sm:px-6'
          }
        },
        side: {
          left: {
            root: 'border-e border-default'
          },
          right: {
            root: ''
          }
        },
        toggleSide: {
          left: {
            toggle: ''
          },
          right: {
            toggle: 'ms-auto'
          }
        }
      }
    }
  }
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        dashboardSidebar: {
          slots: {
            root: 'relative hidden lg:flex flex-col min-h-svh min-w-16 w-(--width) shrink-0',
            header: 'h-(--ui-header-height) shrink-0 flex items-center gap-1.5 px-4',
            body: 'flex flex-col gap-4 flex-1 overflow-y-auto px-4 py-2',
            footer: 'shrink-0 flex items-center gap-1.5 px-4 py-2',
            toggle: '',
            handle: '',
            content: 'lg:hidden',
            overlay: 'lg:hidden'
          },
          variants: {
            menu: {
              true: {
                header: 'sm:px-6',
                body: 'sm:px-6',
                footer: 'sm:px-6'
              }
            },
            side: {
              left: {
                root: 'border-e border-default'
              },
              right: {
                root: ''
              }
            },
            toggleSide: {
              left: {
                toggle: ''
              },
              right: {
                toggle: 'ms-auto'
              }
            }
          }
        }
      }
    })
  ]
})

更新日志

v4.5.0昨天

2663d— feat(DashboardSidebar/Header): 添加 autoClose 属性 (#6089)
c9704— feat(Theme): 新组件 (#4387)

v4.3.02 个月前

184ea— chore(components): 通过省略操作按钮的链接属性来减少类型的冗余

v4.2.03 个月前

dd81d— feat(components): 添加 data-slot 属性 (#5447)

v4.1.04 个月前

63c0a— feat(components): 在使用的插槽属性中暴露 ui (#5207)

v4.0.15 个月前

fface— fix(DashboardPanel/DashboardSidebar): 处理 RTL（从右至左）模式 (#5109)

v3.3.16 个月前

5cb65— feat: 导入 @nuxt/ui-pro 组件 (#4675)

DashboardSearchButton

一个预设样式的按钮，用于打开 DashboardSearch 模态框。

DashboardSidebarCollapse

用于在桌面端折叠侧边栏的按钮。