Ordo UI
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*booleanfalse—
children*ReactNode——
className*string——
expandLabel*string——
collapseLabel*string——

源码

packages/patterns/src/components/sidebar-panel.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

右侧栏折叠面板:圆角矩形 ↔ 圆角胶囊二态;标题与内容经 props 注入。