SideSheet 设计文档

滑动侧边栏:从视口四边(left/right/top/bottom)滑入的浮层容器,承载二级操作页面 / 详情 / 表单 / 筛选,比 Modal 提供更大可滚动内容区。DOM 结构与类名严格对齐 Semi:wrapper(.cd-sidesheet-{placement}) > mask + inner(.cd-sidesheet-inner.cd-sidesheet-inner-wrap.cd-sidesheet-size-{size}, role=dialog tabindex=-1) > content > header(role=heading aria-level=1)+body+footer。Portal 到 getPopupContainer()/body 脱离父层叠上下文;role=dialog,mask 时加 aria-modal;closeOnEsc(默认 false)时 window 监听 Esc 关闭;mask=true 默认锁 body 滚动(disableScroll),getPopupContainer 指向非 body 时为 popup 模式(wrapper position:static)。mask=false 为可操作外部区域形态(无遮罩、面板 box-shadow: --cd-shadow-elevated、宽度落在 wrapper)。size(small448/medium684/large920,默认 small) 仅 left/right 生效;width(默认 448,left/right)/ height(默认 400,top/bottom)显式覆盖。进出场动画对齐 Semi CSSAnimation:mask 淡入淡出 + inner 按 placement 滑入滑出,animationend 后卸载;motion=false 或 prefers-reduced-motion 退化即时显隐。关闭按钮用 IconButton(type=tertiary theme=borderless size=small)+ IconClose。受控 visible(不回写),仅经 onCancel(e) 通知;afterVisibleChange 于动画结束回调可见状态。keepDOM 关闭保留 DOM。

← API 文档

使用建议

承载二级操作页面 / 详情 / 筛选 / 表单;模态用 mask=true,可操作外部区域用 mask=false。承载单一确认/决策用 Modal,不要混用。

危险操作

footer 危险操作(删除/清空等不可逆)使用 --cd-color-danger 与具体动词文案,并由业务侧在 onCancel 对未保存内容做二次确认。

Accessibility

  • wrapper > inner role=dialog tabindex=-1(mask=true 加 aria-modal=true);内部 header role=heading aria-level=1;有 title 用 aria-labelledby,无则 ariaLabel;closeOnEsc 控制 Esc 关闭;关闭按钮 aria-label 经 SideSheet.closeAriaLabel;reduced-motion / motion=false 退化即时显隐。

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

设计变量

该组件暂无专属设计变量。

相关组件