Web Shell 侧栏定制

配置 Home、导航、品牌、会话按钮和嵌入式侧栏的默认行为。

This page has not been translated into English yet. The original Chinese version is shown below.

WebShellWithProviders 的 sidebar 控制会话列表与导航。当前省略 sidebar、设为 true 或传入空对象都会显示 Home 侧栏；要隐藏必须显式使用 false 或 { enabled: false }。

默认布局与升级变化

默认只有 Home、New task 和底部折叠控件，宽度 300px。配置另一个可用主入口或 footer action 后，增加 56px 图标栏，默认总宽 356px；没有公开 layout 选项用于任意替换这一结构。

早期版本省略 sidebar 会隐藏它，启用后省略菜单列表又会显示全部内置项。升级嵌入宿主时必须核对这两个默认变化；独立 Web Shell 自己显式配置完整菜单。

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

export function EmbeddedShell() {
  return (
    <WebShellWithProviders
      baseUrl="http://localhost:4170"
      sidebar={{
        primaryNav: { items: ['newTask', 'plugins'] },
        footer: { items: ['theme', 'collapse'] },
        showSessionSourceSwitch: false,
        sessionActions: {
          items: ['details', 'rename', 'export', 'pin'],
          inlineItems: ['pin', 'rename'],
        },
      }}
    />
  );
}

示例的地址仍需满足同源与认证要求，单纯传入 baseUrl 不会改变浏览器 Origin 策略。

品牌与主导航

默认品牌按 brand prop、daemon GET /brand、内置 Qwen 品牌的顺序解析。branding.render 替换整行并拥有更高优先级；branding: false 隐藏品牌行。branding.hideWhenCompact 默认 false，需旧的紧凑隐藏行为时显式设为 true。

primaryNav.items 可列出 newTask、plugins、channels、live、workflows、managed、scheduledTasks、goals。Home 始终存在；省略列表仅显示 New task，空数组移除所有内置主按钮，render 可追加自定义内容。

live 还要求 showLive，workflows 和 managed 分别要求相应支持与 provider。列入菜单不等于使后端能力可用。

footer 默认仅 collapse，可选 settings、update、localFiles、desktopRelay、workspacesOverview、version、theme、sessionsOverview、splitView、daemonStatus、collapse；部分项有能力或容器宽度条件。图标栏布局中多数动作和版本放入 More，折叠按钮留在底部。

footer: false 隐藏 footer，但移动抽屉仍保留关闭按钮。scheduledTasks 和 goals 属于 primaryNav，不再由 footer.items 控制。自定义 render 内容仍位于宽 Home 列。

showSessionSourceSwitch 默认 true。设为 false 会把活动、归档、主列和次列查询都固定为 sourceType: "default"，不只是隐藏一个切换按钮。独立 Channels 入口可用时会替代来源 tabs。

showLive 默认 false。设为 true 且没有 live 主入口时，Live 仍在 Home 分组与 Experimental 设置中；同时加入 live 入口时，使用独立会话列和设置页。

会话行操作

items 是主开关，可选 details、rename、group、export、delete、pin、archive。inlineItems 只支持 pin、rename、export、delete，默认 ['pin']；details、group、archive 仅在下拉菜单中。

行内按钮必须同时通过 items、inlineItems 和内置能力条件。inlineItems: [] 可隐藏全部行内按钮；没有可用下拉项目时也隐藏菜单触发器。当前会话或正在运行一轮的会话不能归档，因为 daemon 归档会关闭活动会话。

hideProjectHeader 默认 false。设为 true 会隐藏 Projects 标题、相关操作与搜索栏，但保留会话列表和归档会话。

宽度、折叠与可定制边界

拖动宽度保存到 localStorage，恢复时下限为 Home 220px、带图标栏 276px；不会给旧保存值盲目增加 56px。折叠偏好使用 qwen-code-web-shell-sidebar-collapsed 保存。

侧栏、紧凑抽屉和欢迎区域按 shell 容器宽度在 760px 切换；聊天消息仍使用 viewport 断点。split 可用宽度为 1024px，分栏侧栏空间使用 1200px。移动抽屉开关不覆盖已保存的桌面宽度和折叠偏好。

目前会话行 renderer、workspace section、数据源与 resize handle 没有逐项外部替换入口。可通过 onNewSession、onLoadSession、onSessionIdChange、splitSessionIds，以及 theme/language 回调影响宿主行为；不能把这些 props 当作任意替换列表内部实现的接口。