WebShell 侧边栏 — 自定义指南

import { WebShellWithProviders } from '@qwen-code/web-shell';

<WebShellWithProviders
  baseUrl="http://localhost:4170"
  sidebar={true} // 简单启用
  // 或使用细粒度选项：
  // sidebar={{ enabled: true, defaultCollapsed: false, ... }}
/>;

┌─────────────────────────────────────┐
│ ① 品牌区（topRow）                   │  ✅ 可自定义
├─────────────────────────────────────┤
│ ② 主导航                             │  ✅ 可自定义
│    [＋ 新任务]  [🧩 插件]            │
│    [📅 定时任务] [🎯 目标]           │
│    [自定义渲染...]                    │
├─────────────────────────────────────┤
│ ③ 项目头部                           │  ✅ 显示/隐藏
│    📁 项目 ▼ [🔍] [＋]              │
│    会话列表条目...                    │
│    📦 已归档会话                      │
├─────────────────────────────────────┤
│ ④ 底部操作栏                         │  ✅ 可自定义
│    [⚙ 设置] v0.19 [☀] [▦] [◧]      │
├─────────────────────────────────────┤
│ ⑤ 拖拽手柄                           │  ❌ 不可自定义
└─────────────────────────────────────┘

interface WebShellSidebarBranding {
  render?: () => ReactNode; // 替换整个品牌行
  hideWhenCompact?: boolean; // 侧边栏折叠时隐藏（默认：true）
}

sidebar={{
  branding: {
    render: () => (
      <div style={{ display: 'flex', gap: 8 }}>
        <img src="/my-logo.svg" alt="" width={24} />
        <span>My App</span>
      </div>
    ),
  },
}}

type WebShellSidebarPrimaryNavItem =
  | 'newTask' // ✏️ 新任务按钮
  | 'plugins' // 🧩 插件按钮
  | 'scheduledTasks' // 📅 定时任务按钮
  | 'goals'; // 🎯 目标按钮

interface WebShellSidebarPrimaryNavOptions {
  items?: readonly WebShellSidebarPrimaryNavItem[]; // 显示哪些内置按钮（默认：全部）
  render?: () => ReactNode; // 内置按钮之后的额外自定义内容
}

sidebar={{
  primaryNav: {
    items: ['plugins', 'scheduledTasks'],  // 隐藏 newTask 和 goals
    render: () => (
      <button onClick={() => console.log('custom action')}>
        🔗 数据同步
      </button>
    ),
  },
}}

type WebShellSidebarFooterItem =
  | 'settings' // ⚙ 设置面板
  | 'version' // 版本标签（例如 "v0.19.10"）
  | 'theme' // ☀/🌙 亮色/暗色切换
  | 'sessionsOverview' // ▦ 会话概览面板
  | 'splitView' // ◧ 分屏视图（仅大屏幕）
  | 'daemonStatus' // 📊 daemon 状态面板
  | 'collapse'; // ◁/▷ 折叠/展开切换

interface WebShellSidebarFooterOptions {
  items?: readonly WebShellSidebarFooterItem[]; // 显示哪些内置项（默认：全部）
  render?: () => ReactNode; // 在左侧、内置项之前渲染的自定义内容
}

sidebar={{
  footer: { items: ['theme', 'collapse'] },  // 极简底部栏
}}

sidebar={{
  footer: {
    items: ['collapse'],
    render: () => (
      <button onClick={() => openHelpCenter()}>
        ❓ 帮助
      </button>
    ),
  },
}}

interface WebShellSidebarOptions {
  enabled?: boolean; // 显示/隐藏侧边栏（传入时为 true）
  defaultCollapsed?: boolean; // 初始折叠状态（持久化到 localStorage）
  showCompactToggle?: boolean; // 在聊天区域显示折叠按钮（默认：true）
  showSessionSourceSwitch?: boolean; // 显示 Tasks/Channels 切换（默认：true）
  showLive?: boolean; // 显示 daemon 拥有的 Live 会话（默认：false）
  branding?: false | WebShellSidebarBranding;
  primaryNav?: WebShellSidebarPrimaryNavOptions;
  hideProjectHeader?: boolean; // 隐藏"项目"头部行（默认：false = 显示）
  sessionActions?: WebShellSidebarSessionActionsOptions;
  footer?: false | WebShellSidebarFooterOptions;
}

sidebar={{
  showSessionSourceSwitch: false,
}}

sidebar={{
  showLive: true,
}}

sidebar={{
  hideProjectHeader: true,  // 隐藏"项目 ▼ [🔍] [＋]"行
}}

type WebShellSidebarSessionActionItem =
  | 'details' // 📝 详情（下拉子菜单）
  | 'rename' // ✏️ 重命名（下拉菜单）
  | 'group' // 📁 分组/移动到文件夹（下拉菜单）
  | 'export' // 📤 导出聊天记录（下拉菜单）
  | 'delete' // 🗑 删除会话（下拉菜单）
  | 'pin' // 📌 置顶/取消置顶（内联按钮）
  | 'archive'; // 📦 归档（下拉菜单）

/** Subset with working inline (hover-button) handlers. */
type WebShellSidebarSessionInlineActionItem =
  | 'pin'
  | 'rename'
  | 'export'
  | 'delete';

interface WebShellSidebarSessionActionsOptions {
  items?: readonly WebShellSidebarSessionActionItem[]; // 显示哪些操作（默认：全部）
  inlineItems?: readonly WebShellSidebarSessionInlineActionItem[]; // 哪些项作为内联按钮显示（默认：['pin']）
}

sidebar={{
  sessionActions: {
    items: ['details', 'rename', 'export', 'delete', 'pin'],  // 显示哪些操作（主控）
    inlineItems: ['pin', 'delete'],  // pin + delete 作为内联按钮
  },
}}