PatternsLayout & Shells
SidebarPanel
@mox-hub/patterns 模式 · Layout & Shells · canonical
sidebar-panel@mox-hub/patternsLayout & Shellscanonicalsrc/components/sidebar-panel.tsx变体演示sidebar-panel
执行详情
面板内容
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title* | string | — | — |
| icon* | ReactNode | — | — |
| iconClassName* | string | — | — |
| action* | ReactNode | — | — |
| collapsed* | boolean | — | — |
| onToggle* | () => void | — | — |
| defaultCollapsed* | boolean | false | — |
| children* | ReactNode | — | — |
| className* | string | — | — |
| expandLabel* | string | — | — |
| collapseLabel* | string | — | — |
源码
import { useState, type ReactNode } from 'react';
import { ChevronDown } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { RawButton } from '@mox-hub/ui/components/raw/raw-button';
import { usePatternLabels } from '../lib/i18n';
/**
* SidebarPanel - 右侧栏统一「圆角矩形 ↔ 圆角胶囊」折叠面板
*
* 约定:
* - 展开为圆角矩形、收起为仅标题行的紧凑胶囊;两种状态的圆角弧度一致(都为较小直径圆角)。
* - 标题区支持图标(可彩色)/ 标题 / 收缩三角 / 右侧自定义 action;标题区与内容区同背景、无分割线。
* - 展开 / 收起带有流畅动画(行高 grid 动画 + 三角旋转 + 圆角过渡)。
*
* 支持受控(传入 collapsed / onToggle)与不受控(defaultCollapsed)两种用法。
*/
export interface SidebarPanelProps {
title: string;
/** 标题区图标(支持彩色图标,配合 iconClassName 控制颜色) */
icon?: ReactNode;
/** 图标颜色类,如 "text-accent-purple" */
iconClassName?: string;
/** 标题右侧额外的自定义内容(显示在收缩三角之前) */
action?: ReactNode;
/** 受控:是否收起 */
collapsed?: boolean;
/** 受控:折叠切换回调 */
onToggle?: () => void;
/** 不受控:初始是否收起(默认展开) */
defaultCollapsed?: boolean;
children: ReactNode;
className?: string;
/** 展开态 aria-label;默认「展开」 */
expandLabel?: string;
/** 收起态 aria-label;默认「收起」 */
collapseLabel?: string;
}
export function SidebarPanel({
title,
icon,
iconClassName,
action,
collapsed: collapsedProp,
onToggle,
defaultCollapsed = false,
children,
className,
expandLabel,
collapseLabel,
}: SidebarPanelProps) {
const D = usePatternLabels('sidebarPanel', {
expandLabel: '展开',
collapseLabel: '收起',
});
const [open, setOpen] = useState(!defaultCollapsed);
const collapsed = collapsedProp !== undefined ? collapsedProp : !open;
const toggle = onToggle ?? (() => setOpen((v) => !v));
const toggleLabel = collapsed
? (expandLabel ?? D.expandLabel)
: (collapseLabel ?? D.collapseLabel);
return (
<div
className={cn(
// 磨砂底(bg-card/80)、无标题/内容分割线;圆角在展开/收起间保持一致的小圆角并做过渡
'rounded-xl border border-(--panel-subtle-border) bg-(--panel-subtle-bg) backdrop-blur-(--panel-subtle-blur) shadow-xs transition-[border-radius] duration-slow',
className,
)}
>
{/* 标题区 */}
<div className="flex items-center gap-1.5 px-3 py-2">
{icon ? (
<span className={cn('shrink-0', iconClassName)}>{icon}</span>
) : null}
<span className="min-w-0 flex-1 truncate text-xs font-semibold tracking-wide text-muted-foreground">
{title}
</span>
{action ? <span className="flex shrink-0 items-center">{action}</span> : null}
<RawButton
type="button"
onClick={toggle}
className="size-control-xs inline-flex shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
aria-label={toggleLabel}
aria-expanded={!collapsed}
>
<ChevronDown
className={cn(
'size-3 transition-transform duration-slow',
!collapsed && 'rotate-180',
)}
/>
</RawButton>
</div>
{/* 内容区:grid-rows 动画实现流畅展开 / 收起 */}
<div
className={cn(
'grid transition-[grid-template-rows] duration-slow ease-out',
collapsed ? 'grid-rows-[0fr]' : 'grid-rows-[1fr]',
)}
// 收起后内容高度为 0,但仍留在 DOM;inert 同时移出 Tab 序列与无障碍树
inert={collapsed}
aria-hidden={collapsed || undefined}
data-collapsed={collapsed || undefined}
>
<div className="overflow-hidden">
<div className="px-2 pb-2 flex flex-col gap-0.5">{children}</div>
</div>
</div>
</div>
);
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
右侧栏折叠面板:圆角矩形 ↔ 圆角胶囊二态;标题与内容经 props 注入。