开发预览更新于 2026-05-10

Sidebar 侧栏

竖直主导航，支持分组、嵌套子菜单、徽标、收起为图标模式。

基础用法

items 接受两种条目：普通 SidebarItem（叶子菜单）或 SidebarGroup（分组容器，type: 'group' + items[]）。v-model 绑定当前选中的 key，defaultOpenKeys 控制初始展开的有 children 的项。

背景

当前选中：analytics

<script setup lang="ts">
import { ref } from 'vue';
import { CfSidebar, type SidebarEntry } from '@chufix-design/vue';

const active = ref('analytics');
const items: SidebarEntry[] = [
  {
    type: 'group',
    label: '工作台',
    items: [
      { key: 'overview', label: '概览' },
      { key: 'analytics', label: '分析', badge: '12' },
      { key: 'reports', label: '报表' },
    ],
  },
  {
    type: 'group',
    label: '资源',
    items: [
      {
        key: 'team',
        label: '团队',
        children: [
          { key: 'members', label: '成员' },
          { key: 'roles', label: '角色' },
          { key: 'invitations', label: '邀请', badge: 3 },
        ],
      },
      { key: 'settings', label: '设置' },
      { key: 'billing', label: '账单', disabled: true },
    ],
  },
];
</script>

<template>
  <div style="height: 360px; display:flex; gap: 12px;">
    <div style="border: 1px solid var(--line-1); border-radius: 8px; overflow: hidden;">
      <CfSidebar
        v-model="active"
        :items="items"
        :default-open-keys="['team']"
      />
    </div>
    <div style="flex:1; padding: 12px; color: var(--fg-2); font-size: 12px;">
      当前选中：<code>{{ active }}</code>
    </div>
  </div>
</template>

import { useState } from 'react';
import { CfSidebar, type SidebarEntry } from '@chufix-design/react';

const items: SidebarEntry[] = [/* ... */];

export default function Demo() {
const [active, setActive] = useState('analytics');
return (
  <CfSidebar
    value={active}
    items={items}
    defaultOpenKeys={['team']}
    onChange={setActive}
  />
);
}

收起为图标

collapsed 把侧栏宽度缩到 56px，只显示图标 + tooltip（鼠标悬停显示 title）。这种模式下子菜单不再展开，需要在你的应用层面接管交互。

背景

<script setup lang="ts">
import { ref } from 'vue';
import { CfSidebar, CfButton, type SidebarEntry } from '@chufix-design/vue';

const active = ref('overview');
const collapsed = ref(true);
const homeIcon = '<svg viewBox="0 0 16 16" fill="none"><path d="M3 7l5-4 5 4v6a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V7z" stroke="currentColor" stroke-width="1.4"/></svg>';
const chartIcon = '<svg viewBox="0 0 16 16" fill="none"><path d="M3 13V8m4 5V5m4 8V9" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"/></svg>';
const usersIcon = '<svg viewBox="0 0 16 16" fill="none"><circle cx="6" cy="6" r="2.5" stroke="currentColor" stroke-width="1.4"/><path d="M2 13a4 4 0 0 1 8 0M11 8.5a2 2 0 1 0 0-4 2 2 0 0 0 0 4zM10.5 13a3 3 0 0 1 4-2.5" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"/></svg>';
const cogIcon = '<svg viewBox="0 0 16 16" fill="none"><circle cx="8" cy="8" r="2.2" stroke="currentColor" stroke-width="1.4"/><path d="M8 1.5v2M8 12.5v2M14.5 8h-2M3.5 8h-2M12.6 3.4l-1.4 1.4M4.8 11.2l-1.4 1.4M12.6 12.6l-1.4-1.4M4.8 4.8 3.4 3.4" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"/></svg>';

const items: SidebarEntry[] = [
  { key: 'overview', label: '概览', icon: homeIcon },
  { key: 'analytics', label: '分析', icon: chartIcon, badge: '12' },
  { key: 'team', label: '团队', icon: usersIcon },
  { key: 'settings', label: '设置', icon: cogIcon },
];
</script>

<template>
  <div style="display:flex; gap: 12px; align-items: flex-start;">
    <CfButton size="sm" variant="tertiary" @click="collapsed = !collapsed">
      {{ collapsed ? '展开' : '收起' }}
    </CfButton>
    <div style="border: 1px solid var(--line-1); border-radius: 8px; overflow: hidden;">
      <CfSidebar v-model="active" :items="items" :collapsed="collapsed" />
    </div>
  </div>
</template>

<CfSidebar value={active} items={items} collapsed onChange={setActive} />

徽标 + 禁用

item.badge 接收数字或字符串，渲染在 label 右侧。item.disabled 灰显且不响应点击。

背景

<script setup lang="ts">
import { ref } from 'vue';
import { CfSidebar, type SidebarEntry } from '@chufix-design/vue';

const active = ref('inbox');
const items: SidebarEntry[] = [
  { key: 'inbox', label: '收件箱', badge: 12 },
  { key: 'starred', label: '加星' },
  { key: 'sent', label: '已发送' },
  { key: 'drafts', label: '草稿', badge: 'NEW' },
  { key: 'trash', label: '已删除', disabled: true },
];
</script>

<template>
  <CfSidebar v-model="active" :items="items" />
</template>

<CfSidebar value={active} items={items} onChange={setActive} />

三档尺寸

size —— sm（紧凑型，适合多级嵌套或多条目）/ md / lg（触摸友好）。

背景

<script setup lang="ts">
import { ref } from 'vue';
import { CfSidebar, type SidebarEntry } from '@chufix-design/vue';

const a = ref('overview');
const b = ref('overview');
const c = ref('overview');

const items: SidebarEntry[] = [
  { key: 'overview', label: '概览' },
  { key: 'analytics', label: '分析' },
  { key: 'reports', label: '报表' },
  { key: 'settings', label: '设置' },
];
</script>

<template>
  <div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px;">
    <CfSidebar v-model="a" :items="items" size="sm" />
    <CfSidebar v-model="b" :items="items" size="md" />
    <CfSidebar v-model="c" :items="items" size="lg" />
  </div>
</template>

<CfSidebar value={a} onChange={setA} items={items} size="sm" />
<CfSidebar value={b} onChange={setB} items={items} size="md" />
<CfSidebar value={c} onChange={setC} items={items} size="lg" />

API

属性	类型	默认值	说明
`items`	`SidebarEntry[]`	`[]`	菜单条目，可混排叶子和分组
`modelValue` (Vue) / `value` (React)	`string`	`—`	当前选中的 `item.key`
`openKeys` / `defaultOpenKeys`	`string[]`	`—`	受控 / 非受控的展开 key 列表
`collapsed`	`boolean`	`false`	是否收成 56px 图标模式
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	字号 + 内距

SidebarItem：{ key, label, icon?, href?, badge?, disabled?, children? }。 SidebarGroup：{ type: 'group', key?, label?, items[] }。

事件：update:modelValue / update:openKeys / select（React 端：onChange / onOpenKeysChange / onSelect）。

与 AppShell 配合使用时，把 <CfSidebar> 放到 #sidebar slot 即可拼出完整后台壳。