文案规范
使用建议
用于 AI 产品右侧信息/配置面板(工具配置、引用溯源、内容预览)。仅需可伸缩浮层用 SideBarContainer;通用抽屉用 SideSheet;侧边导航用 Nav。Container 与主壳分层解耦——SideBarContainer 提供浮层壳,SideBar 提供 mode 路由内容,通常内嵌 <SideBarContainer><SideBar/></SideBarContainer>。
相关组件
更多通用文案规范见 文案规范指南。
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)
SideBar mode=main + 顶部 Options 图标 tab 组(roving tabindex)
mode 路由 main↔detail,详情返回按钮 onBackWard(可异步)
SideBarAnnotation:Collapse 分组折叠 + video/text 引用卡片(可点击打开来源,时长/序号本地化)
SideBarCodeContent 折叠列表:isJson 用 JsonViewer,否则 CodeHighlight;onExpand 全屏回调
SideBarMcpConfigure:内置/自定义双列表 + 搜索过滤 + 启用开关(role=switch)+ 配置/编辑/添加动作
SideBarFileContent 折叠列表:每项 tiptap 编辑器(editable 控查看/编辑,编辑态带格式工具栏 + 图片上传节点),tiptap 全程动态 import
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
mode | 展示模式,main 主视图,其余详情视图 | 'main' | 'code' | 'file' | string | 'main' |
activeKey | 主视图激活 option(受控,不回写) | string | undefined |
options | 顶部图标 tab 组({ icon, name, key }) | SideBarOption[] | [] |
onActiveOptionChange | option 切换回调 | (e: Event, key: string) => void | undefined |
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 | 根自定义类名 | string | undefined |
style | 根自定义内联样式 | string | undefined |
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
visible | 是否可见(受控,不回写;仅经 onCancel 通知) | boolean | false |
title | 标题 | string | Snippet | undefined |
onCancel | 关闭回调(Esc / 关闭按钮) | (e: Event) => void | undefined |
afterVisibleChange | 动画结束后(入场或出场)触发 | (v: boolean) => void | undefined |
motion | 展开/收起动画;false 等价即时显隐 | boolean | true |
resizable | 宽度可拖拽(复用 Resizable 把手 + 键盘 a11y) | boolean | true |
minWidth | 最小宽度 | string | number | 150 |
maxWidth | 最大宽度 | string | number | undefined |
defaultSize | 默认尺寸(当前消费 width) | { width?; height? } | undefined |
showClose | 显示关闭按钮 | boolean | true |
renderHeader | 自定义头部(覆盖 title + 关闭按钮) | Snippet | undefined |
class | 面板自定义类名 | string | undefined |
style | 面板自定义内联样式 | string | undefined |
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
info | 分组数组({ header, key, annotations }[]),每组一个折叠面板 | SideBarAnnotationGroup[] | [] |
activeKey | 展开的分组 key(受控,不回写;透传 Collapse) | string | string[] | undefined |
onChange | 展开变更回调(当前展开 key 数组) | (keys: string[]) => void | undefined |
onClick | 点击某条引用(url 存在先在新窗口打开来源) | (e: Event, item) => void | undefined |
renderItem | 自定义单条渲染(覆盖默认 video/text 卡片) | Snippet<[SideBarAnnotationItem]> | undefined |
...Container | 继承并透传全部 Container props(visible/title/onCancel/resizable/... );title 默认走 i18n annotationTitle | SideBarContainer props | — |
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
codes | 代码/JSON 预览项列表;每项按 isJson 分流 JsonViewer / CodeHighlight | CodeItemProps[] | [] |
activeKey | 受控展开项 key(受控,不回写;仅经 onChange 通知,内部兜底非受控) | string | string[] | undefined |
onChange | 展开态变化回调(Collapse onChange) | (keys: string[]) => void | undefined |
onExpand | 点击某项展开(全屏)按钮回调;mode 固定 "code"(对齐 Semi onExpand) | (e: MouseEvent, code: CodeItemProps, mode: string) => void | undefined |
class | 根自定义类名 | string | undefined |
style | 根自定义内联样式 | string | undefined |
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
options | 内置 MCP 工具列表(受控);每项 { value, label, icon?, desc?, active?, disabled?, configure? } | SideBarMcpOption[] | [] |
customOptions | 自定义 MCP 工具列表(受控);空时显示添加入口 | SideBarMcpOption[] | [] |
filter | 自定义搜索过滤谓词(覆盖默认 label/value 大小写不敏感包含匹配) | (input: string, option: SideBarMcpOption) => boolean | undefined |
placeholder | 搜索占位(覆盖 i18n mcpSearchPlaceholder,修 Semi 硬编码「请输入」) | string | undefined |
onSearch | 搜索输入回调(custom 恒 false) | (input: string, custom: boolean) => void | undefined |
onStatusChange | 启用/关闭变化:产出该组「下一份数组」+ custom 标记(不回写 prop) | (options: SideBarMcpOption[], custom: boolean) => void | undefined |
onAddClick | 自定义组「添加」按钮回调 | (e: MouseEvent) => void | undefined |
onConfigureClick | 内置工具(configure=true)「配置」按钮回调 | (e: MouseEvent, option: SideBarMcpOption) => void | undefined |
onEditClick | 自定义工具「编辑」按钮回调 | (e: MouseEvent, option: SideBarMcpOption) => void | undefined |
renderItem | 自定义单项渲染(覆盖默认项,custom 标记来自自定义组) | Snippet<[{ option; custom }]> | undefined |
...Container | 继承并透传全部 Container props(visible/title/onCancel/resizable/... );title 默认走 i18n mcpTitle | SideBarContainer props | — |
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
files | 富文本文件项列表;每项 { key, name, content, editable, onContentChange, extensions, imgUploadProps },一个 tiptap 编辑器(editable 控制查看/编辑,默认只读) | FileItemProps[] | [] |
activeKey | 受控展开项 key(受控,不回写;仅经 onChange 通知,内部兜底非受控) | string | string[] | undefined |
onChange | 展开态变化回调(Collapse onChange) | (keys: string[]) => void | undefined |
onExpand | 点击某项展开(全屏)按钮回调;mode 固定 "file"(对齐 Semi onExpand) | (e: MouseEvent, file: FileItemProps, mode: string) => void | undefined |
class | 根自定义类名 | string | undefined |
style | 根自定义内联样式 | string | undefined |
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
content | 初始富文本内容(HTML) | string | undefined |
editable | 是否可编辑(false=只读查看,渲染工具栏与否由此决定) | boolean | true |
onContentChange | 内容变更回调(editor.getHTML()) | (html: string) => void | undefined |
extensions | 追加到默认扩展集末尾的自定义 tiptap 扩展(对齐 Semi extensions) | Extension[] | [] |
imgUploadProps | 图片上传配置(透传 ImageUploadNode / 内嵌 Upload;含 action/accept/getUploadImageSrc 等) | SideBarImageUploadOptions | undefined |
class | 根自定义类名 | string | undefined |
style | 根自定义内联样式 | string | undefined |
| APG | dialog + 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 展开/收起过渡时长(组件消费) |