SideBar

AI 侧边信息栏套件(重量级组合,分阶段交付):P0 SideBarContainer 为可伸缩浮层壳——贴视口右侧(RTL 贴左),role=dialog + aria-labelledby(title),打开移焦 + focus-trap 焦点捕获/归还 + Esc 关闭,堆叠 z-index 与 Modal/SideSheet 统一层栈(后开者在上),resizable 时左边缘(RTL 右边缘)把手拖拽调宽——复用 core createResizeDrag(axis:x 单轴 + clamp minWidth/maxWidth)与 Resizable 同套把手 a11y(role=separator + aria-orientation=vertical + aria-valuenow + 键盘 ←→/Home/End),motion 展开/收起为 CSS transition(reduced-motion / motion=false 退化即时显隐)。P1 SideBar 主壳按 mode 路由:main 渲染顶部 Options 图标 tab 组(role=tablist + roving tabindex + 键盘,name 作无障碍名)+ renderMainContent(activeKey);detail(code/file/自定义)渲染 renderDetailHeader + 返回按钮(onBackWard 可异步,await 期间禁用防重触发)+ renderDetailContent(mode)。受控 visible / activeKey(不回写,仅回调通知)。P2 SideBarAnnotation 参考来源/引用溯源:外层复用 SideBarContainer 浮层壳(透传全部 Container props,title 默认走 i18n annotationTitle),内部用 Collapse 渲染 info 分组(每组一折叠面板 + aria-expanded),展开区渲染 video(封面/时长/播放态,duration 走 locale 数值格式化为 mm:ss)/text(站点 logo/名称/引用序号)卡片;可点击卡片(url 或 onClick)用原生 button(键盘 Enter/Space + focus 环 + 时长/序号本地化可访问文本),renderItem 可整条覆盖。P4 SideBarCodeContent 代码/JSON 预览:Collapse 折叠列表,每项按 isJson 分流 JsonViewer / CodeHighlight(透传 jsonViewerProps/codeHighlightProps),onExpand 全屏回调。P3 SideBarMcpConfigure MCP 工具配置面板:外层复用 SideBarContainer(title 默认走 i18n mcpTitle),内部顶部已启用计数 + 搜索框(Input,前缀放大镜 + aria-label,headless filterMcpOptions 支持自定义 filter)+ 内置/自定义双列表并列(Semi 为 radio 二选一,本库改并列双列表更直观);每项前置图标(string→img / Snippet)+ label + desc + 动作按钮(内置 configure 显示配置 / 自定义显示编辑,aria-label 含工具名)+ 启用开关(复用本库 Switch,原生 role=switch + aria-checked,disabled 预设项锁定 + title tooltip),启用变化经 core toggleMcpOptionActive 产出「下一份数组 + custom 标记」上抛 onStatusChange 不回写;自定义组空态显示添加按钮,无搜索结果显示提示。P5 SideBarFileContent 富文本查看/编辑:Collapse 折叠列表,每项 SideBarFileItem 一个 tiptap v3 编辑器(editable 控查看/编辑,编辑态渲染格式工具栏),默认扩展集对齐 Semi(StarterKit link openOnClick:false + TextStyleKit + Image + TextAlign + 自研 SelectionMark + 自研 ImageUploadNode,末尾拼接 extensions),onContentChange 回调 editor.getHTML();ImageUploadNode 用 svelte-tiptap NodeViewRenderer 内嵌本库 Upload(draggable + getUploadImageSrc);tiptap 内核 + 3 官方扩展(text-style/image/text-align)+ svelte-tiptap 全程动态 import 不进主 bundle。

设计文档

如何引入

import { SideBar, SideBarContainer, SideBarAnnotation, SideBarCodeContent, SideBarMcpConfigure, SideBarFileContent, SideBarFileItem } from '@chenzy-design/svelte';

基础容器

SideBarContainer 贴右浮层壳:role=dialog + focus-trap + Esc 关闭

可伸缩

左边缘拖拽调宽(复用 Resizable createResizeDrag + 键盘 ←→/Home/End)

主视图 Options 切换

SideBar mode=main + 顶部 Options 图标 tab 组(roving tabindex)

详情返回

mode 路由 main↔detail,详情返回按钮 onBackWard(可异步)

参考来源溯源

SideBarAnnotation:Collapse 分组折叠 + video/text 引用卡片(可点击打开来源,时长/序号本地化)

代码/JSON 预览

SideBarCodeContent 折叠列表:isJson 用 JsonViewer,否则 CodeHighlight;onExpand 全屏回调

MCP 工具配置

SideBarMcpConfigure:内置/自定义双列表 + 搜索过滤 + 启用开关(role=switch)+ 配置/编辑/添加动作

富文本查看/编辑

SideBarFileContent 折叠列表:每项 tiptap 编辑器(editable 控查看/编辑,编辑态带格式工具栏 + 图片上传节点),tiptap 全程动态 import

API 参考

SideBar

SideBar

Props

属性说明类型默认值
mode展示模式,main 主视图,其余详情视图'main' | 'code' | 'file' | string'main'
activeKey主视图激活 option(受控,不回写)stringundefined
options顶部图标 tab 组({ icon, name, key })SideBarOption[][]
onActiveOptionChangeoption 切换回调(e: Event, key: string) => voidundefined
renderMainContent主视图内容(按 activeKey 渲染)Snippet<[string | undefined]>undefined
renderDetailContent详情内容(按 mode 渲染)Snippet<[mode]>undefined
renderDetailHeader详情头部(返回按钮之后)Snippet<[mode]>undefined
onBackWard详情返回主视图(可异步,await 期间禁用防重触发)(e: Event, mode) => void | Promise<void>undefined
class根自定义类名stringundefined
style根自定义内联样式stringundefined

SideBarContainer

Props

属性说明类型默认值
visible是否可见(受控,不回写;仅经 onCancel 通知)booleanfalse
title标题string | Snippetundefined
onCancel关闭回调(Esc / 关闭按钮)(e: Event) => voidundefined
afterVisibleChange动画结束后(入场或出场)触发(v: boolean) => voidundefined
motion展开/收起动画;false 等价即时显隐booleantrue
resizable宽度可拖拽(复用 Resizable 把手 + 键盘 a11y)booleantrue
minWidth最小宽度string | number150
maxWidth最大宽度string | numberundefined
defaultSize默认尺寸(当前消费 width){ width?; height? }undefined
showClose显示关闭按钮booleantrue
renderHeader自定义头部(覆盖 title + 关闭按钮)Snippetundefined
class面板自定义类名stringundefined
style面板自定义内联样式stringundefined

SideBarAnnotation

Props

属性说明类型默认值
info分组数组({ header, key, annotations }[]),每组一个折叠面板SideBarAnnotationGroup[][]
activeKey展开的分组 key(受控,不回写;透传 Collapse)string | string[]undefined
onChange展开变更回调(当前展开 key 数组)(keys: string[]) => voidundefined
onClick点击某条引用(url 存在先在新窗口打开来源)(e: Event, item) => voidundefined
renderItem自定义单条渲染(覆盖默认 video/text 卡片)Snippet<[SideBarAnnotationItem]>undefined
...Container继承并透传全部 Container props(visible/title/onCancel/resizable/... );title 默认走 i18n annotationTitleSideBarContainer props

SideBarCodeContent

Props

属性说明类型默认值
codes代码/JSON 预览项列表;每项按 isJson 分流 JsonViewer / CodeHighlightCodeItemProps[][]
activeKey受控展开项 key(受控,不回写;仅经 onChange 通知,内部兜底非受控)string | string[]undefined
onChange展开态变化回调(Collapse onChange)(keys: string[]) => voidundefined
onExpand点击某项展开(全屏)按钮回调;mode 固定 "code"(对齐 Semi onExpand)(e: MouseEvent, code: CodeItemProps, mode: string) => voidundefined
class根自定义类名stringundefined
style根自定义内联样式stringundefined

SideBarMcpConfigure

Props

属性说明类型默认值
options内置 MCP 工具列表(受控);每项 { value, label, icon?, desc?, active?, disabled?, configure? }SideBarMcpOption[][]
customOptions自定义 MCP 工具列表(受控);空时显示添加入口SideBarMcpOption[][]
filter自定义搜索过滤谓词(覆盖默认 label/value 大小写不敏感包含匹配)(input: string, option: SideBarMcpOption) => booleanundefined
placeholder搜索占位(覆盖 i18n mcpSearchPlaceholder,修 Semi 硬编码「请输入」)stringundefined
onSearch搜索输入回调(custom 恒 false)(input: string, custom: boolean) => voidundefined
onStatusChange启用/关闭变化:产出该组「下一份数组」+ custom 标记(不回写 prop)(options: SideBarMcpOption[], custom: boolean) => voidundefined
onAddClick自定义组「添加」按钮回调(e: MouseEvent) => voidundefined
onConfigureClick内置工具(configure=true)「配置」按钮回调(e: MouseEvent, option: SideBarMcpOption) => voidundefined
onEditClick自定义工具「编辑」按钮回调(e: MouseEvent, option: SideBarMcpOption) => voidundefined
renderItem自定义单项渲染(覆盖默认项,custom 标记来自自定义组)Snippet<[{ option; custom }]>undefined
...Container继承并透传全部 Container props(visible/title/onCancel/resizable/... );title 默认走 i18n mcpTitleSideBarContainer props

SideBarFileContent

Props

属性说明类型默认值
files富文本文件项列表;每项 { key, name, content, editable, onContentChange, extensions, imgUploadProps },一个 tiptap 编辑器(editable 控制查看/编辑,默认只读)FileItemProps[][]
activeKey受控展开项 key(受控,不回写;仅经 onChange 通知,内部兜底非受控)string | string[]undefined
onChange展开态变化回调(Collapse onChange)(keys: string[]) => voidundefined
onExpand点击某项展开(全屏)按钮回调;mode 固定 "file"(对齐 Semi onExpand)(e: MouseEvent, file: FileItemProps, mode: string) => voidundefined
class根自定义类名stringundefined
style根自定义内联样式stringundefined

SideBarFileItem

Props

属性说明类型默认值
content初始富文本内容(HTML)stringundefined
editable是否可编辑(false=只读查看,渲染工具栏与否由此决定)booleantrue
onContentChange内容变更回调(editor.getHTML())(html: string) => voidundefined
extensions追加到默认扩展集末尾的自定义 tiptap 扩展(对齐 Semi extensions)Extension[][]
imgUploadProps图片上传配置(透传 ImageUploadNode / 内嵌 Upload;含 action/accept/getUploadImageSrc 等)SideBarImageUploadOptionsundefined
class根自定义类名stringundefined
style根自定义内联样式stringundefined

Accessibility

APGdialog + tablist

参考 WAI-ARIA APG 模式:dialog (modal) + tabs

文案规范

使用建议

用于 AI 产品右侧信息/配置面板(工具配置、引用溯源、内容预览)。仅需可伸缩浮层用 SideBarContainer;通用抽屉用 SideSheet;侧边导航用 Nav。Container 与主壳分层解耦——SideBarContainer 提供浮层壳,SideBar 提供 mode 路由内容,通常内嵌 <SideBarContainer><SideBar/></SideBarContainer>。

相关组件

设计变量

变量默认值用法
--cd-sidebar-motion-duration var(--cd-motion-duration-mid)Container 展开/收起过渡时长(组件消费)