Ordo UI
PatternsLayout & Shells

RightSidebar

@mox-hub/patterns 模式 · Layout & Shells · canonical

right-sidebar@mox-hub/patternsLayout & Shellscanonicalsrc/components/right-sidebar.tsx
变体演示right-sidebar
主内容

Props API

Prop类型默认值说明
hidden*boolean——
width*string | number360—
overlay*booleanfalse—
overlayOpen*boolean——
defaultOverlayOpen*booleanfalse—
onOverlayOpenChange*(open: boolean) => void——
overlayLabel*string——
overlayTitle*string——
overlayDescription*string——
overlayTriggerClassName*string——
className*string——
children*ReactNode——

源码

packages/patterns/src/components/right-sidebar.tsx
import { useEffect, useState, type ReactNode, type ComponentProps } from 'react';
import { PanelRight, PanelRightClose, type LucideIcon } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from '@mox-hub/ui';
import { RawButton } from '@mox-hub/ui/components/raw/raw-button';
import { useDirection } from '@mox-hub/ui/i18n';
import { usePatternLabels } from '../lib/i18n';

/** 与 Tailwind `lg` 断点一致(1024px):窄屏浮层模式在此以下生效。 */
const NARROW_QUERY = '(max-width: 1023px)';

/** 窄屏判定:SSR / jsdom 无 matchMedia 时按桌面处理(与既有 max-lg:hidden 一致)。 */
function useIsNarrow() {
  const [narrow, setNarrow] = useState(false);

  useEffect(() => {
    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
      return;
    }

    const query = window.matchMedia(NARROW_QUERY);
    const onChange = () => setNarrow(query.matches);

    onChange();
    if (typeof query.addEventListener === 'function') {
      query.addEventListener('change', onChange);
      return () => query.removeEventListener('change', onChange);
    }

    // Safari < 14 / jsdom 的旧 matchMedia 实现
    query.addListener(onChange);
    return () => query.removeListener(onChange);
  }, []);

  return narrow;
}

/**
 * RightSidebar - 统一右侧栏容器
 *
 * 与主内容区完全左右并列(flex 行内),通过 `hidden` 实现侧边栏整体收起/展开,
 * 行为与任务详情页一致:收起时不占位(不是浮层/覆盖)。
 *
 * 窄屏(<lg):默认沿用 `max-lg:hidden`;传 `overlay` 后改为内建浮动入口 +
 * Sheet 浮层(自带遮罩与焦点管理),消费方无需改 CSS。桌面宽度行为不变。
 */
export interface RightSidebarProps extends ComponentProps<'aside'> {
  /** 是否隐藏(收起)侧边栏 */
  hidden?: boolean;
  /** 宽度,默认 360px(F 类 F4.2:全站唯一档,320 档已废除) */
  width?: number | string;
  /**
   * 窄屏(<lg)浮层模式:
   * - `false`(默认):保持既有行为,<lg 整体隐藏,入口由消费方自备;
   * - `true`:<lg 渲染浮动入口按钮 + Sheet 浮层;>=lg 仍是原来的并列侧栏。
   */
  overlay?: boolean;
  /** 浮层展开状态(受控);不传则非受控。 */
  overlayOpen?: boolean;
  /** 浮层非受控初始展开状态。 */
  defaultOverlayOpen?: boolean;
  /** 浮层展开状态变化回调。 */
  onOverlayOpenChange?: (open: boolean) => void;
  /** 浮动入口按钮无障碍名;默认「打开详情面板」。 */
  overlayLabel?: string;
  /** 浮层标题(Sheet 可访问名);默认「详情面板」。 */
  overlayTitle?: string;
  /** 浮层描述;默认「窄屏下以浮层展示的详情内容」。 */
  overlayDescription?: string;
  /** 浮动入口按钮附加类名(默认固定在右上角)。 */
  overlayTriggerClassName?: string;
}

export function RightSidebar({
  hidden,
  width = 360,
  overlay = false,
  overlayOpen,
  defaultOverlayOpen = false,
  onOverlayOpenChange,
  overlayLabel,
  overlayTitle,
  overlayDescription,
  overlayTriggerClassName,
  className,
  children,
  ...rest
}: RightSidebarProps) {
  const [internalOpen, setInternalOpen] = useState(defaultOverlayOpen);
  const open = overlayOpen ?? internalOpen;
  const narrow = useIsNarrow();
  const direction = useDirection();
  const D = usePatternLabels('rightSidebar', {
    expandLabel: '展开侧边栏',
    collapseLabel: '收起侧边栏',
    overlayLabel: '打开详情面板',
    overlayTitle: '详情面板',
    overlayDescription: '窄屏下以浮层展示的详情内容',
  });

  const setOpen = (next: boolean) => {
    if (overlayOpen === undefined) setInternalOpen(next);
    onOverlayOpenChange?.(next);
  };

  const widthStyle =
    typeof width === 'number'
      ? { width: `min(${width}px, 100vw)` }
      : { width: `min(${width}, 100vw)` };

  if (overlay && narrow) {
    if (hidden) return null;

    return (
      <>
        <RawButton
          type="button"
          data-slot="right-sidebar-overlay-trigger"
          aria-label={overlayLabel ?? D.overlayLabel}
          aria-haspopup="dialog"
          aria-expanded={open}
          onClick={() => setOpen(true)}
          className={cn(
            'fixed end-3 top-3 z-modal inline-flex size-control-sm items-center justify-center rounded-full border border-border bg-background text-foreground shadow-xs transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 focus-visible:ring-ring/40',
            overlayTriggerClassName,
          )}
        >
          <PanelRight className="size-4" />
        </RawButton>
        <Sheet open={open} onOpenChange={setOpen}>
          <SheetContent
            data-slot="right-sidebar-overlay"
            side={direction === 'rtl' ? 'left' : 'right'}
            style={widthStyle}
            className="max-w-[calc(100vw-2rem)] gap-0 p-0"
          >
            <SheetHeader className="border-b border-border px-4 py-3">
              <SheetTitle>{overlayTitle ?? D.overlayTitle}</SheetTitle>
              <SheetDescription>
                {overlayDescription ?? D.overlayDescription}
              </SheetDescription>
            </SheetHeader>
            <div className="flex flex-col gap-3 overflow-y-auto px-3 py-3">{children}</div>
          </SheetContent>
        </Sheet>
      </>
    );
  }

  return (
    <aside
      hidden={hidden}
      style={widthStyle}
      className={cn(
        // 审计 P2-13 / P2-23:磨砂走 panel token;lg 以下默认隐藏,避免把主栏压到不可用。
        'shrink-0 overflow-y-auto overscroll-contain border-s border-(--panel-border) bg-(--panel-bg) backdrop-blur-(--panel-blur) max-lg:hidden',
        className,
      )}
      {...rest}
    >
      <div className="flex flex-col gap-3 px-3 py-3">{children}</div>
    </aside>
  );
}

/**
 * SidebarButtonGroup - 侧边栏顶部按钮组区域
 * 所有按钮固定在一行内显示(横向排列,不换行)。
 */
export function SidebarButtonGroup({
  className,
  children,
}: {
  className?: string;
  children: ReactNode;
}) {
  return (
    <div className={cn('flex items-center justify-start gap-1.5 whitespace-nowrap', className)}>
      {children}
    </div>
  );
}

/**
 * SidebarButton - 侧边栏内按钮
 * - 默认形态为圆形图标按钮,固定不展开(对外只展示圆形图标)。
 * - `variant="capsule"` 为固定胶囊形按钮(如“指派 AI”主操作)。
 */
export function SidebarButton({
  icon: Icon,
  label,
  onClick,
  variant = 'icon',
  className,
  type = 'button',
  ...rest
}: {
  icon: LucideIcon;
  label: string;
  onClick?: () => void;
  variant?: 'icon' | 'capsule';
} & Omit<ComponentProps<'button'>, 'children'>) {
  if (variant === 'capsule') {
    return (
      <RawButton
        type={type}
        onClick={onClick}
        aria-label={label}
        title={label}
        className={cn(
          'inline-flex h-control-2xs shrink-0 items-center gap-1 px-2.5 text-xs font-medium whitespace-nowrap rounded-full border border-border bg-transparent text-foreground transition-colors hover:bg-muted hover:text-foreground',
          className,
        )}
        {...rest}
      >
        <Icon className="size-3.5 shrink-0" />
        <span className="truncate">{label}</span>
      </RawButton>
    );
  }
  return (
    <RawButton
      type={type}
      onClick={onClick}
      aria-label={label}
      title={label}
      className={cn(
        'inline-flex size-control-2xs shrink-0 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground',
        className,
      )}
      {...rest}
    >
      <Icon className="size-3.5 shrink-0" />
    </RawButton>
  );
}

/**
 * SidebarToggle - 右侧栏展开/收起开关
 * 图标随状态切换:展开时显示“展开态”图标,收起时显示“收起态”图标。
 */
export function SidebarToggle({
  open,
  onToggle,
  className,
  expandLabel,
  collapseLabel,
}: {
  /** 侧边栏当前是否展开 */
  open: boolean;
  onToggle: () => void;
  className?: string;
  /** 展开态 aria-label / title;默认「展开侧边栏」 */
  expandLabel?: string;
  /** 收起态 aria-label / title;默认「收起侧边栏」 */
  collapseLabel?: string;
}) {
  const D = usePatternLabels('rightSidebar', {
    expandLabel: '展开侧边栏',
    collapseLabel: '收起侧边栏',
  });
  const label = open
    ? (collapseLabel ?? D.collapseLabel)
    : (expandLabel ?? D.expandLabel);
  return (
    <RawButton
      type="button"
      onClick={onToggle}
      aria-label={label}
      title={label}
      aria-pressed={open}
      className={cn(
        'inline-flex size-control-2xs shrink-0 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring/50',
        className,
      )}
    >
      {open ? <PanelRightClose className="size-3.5" /> : <PanelRight className="size-3.5" />}
    </RawButton>
  );
}

可访问性与 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。

用法说明

统一右侧栏容器:与主内容 flex 并列,hidden 收起;传 overlay 后窄屏(<lg)提供内建浮动入口 + Sheet 浮层(自带遮罩/焦点管理),桌面行为不变;不做路由或业务取数。

窄屏(<lg)行为

默认沿用 max-lg:hidden:窗口宽度 <1024px 时右栏整体隐藏,入口由消费方自备。需要内建入口时传 overlay:

<RightSidebar overlay width={360}>
  {/* 详情内容 */}
</RightSidebar>
  • 窄屏渲染右上角浮动入口(打开详情面板),点击打开 Sheet 浮层;Sheet 自带遮罩、焦点圈定与关闭后焦点归还。
  • >=lg 仍是原来的并列侧栏,宽度、hidden、样式行为与不传 overlay 完全一致。
  • 受控用法:overlayOpen + onOverlayOpenChange;非受控初始态用 defaultOverlayOpen。
  • 入口位置可用 overlayTriggerClassName 覆写(例如避开页头操作区:top-14)。
  • 文案覆写:overlayLabel / overlayTitle / overlayDescription,或经 I18nProvider 的 rightSidebar section 统一提供。

若产品更希望「窄屏换用独立 Sheet 而非右栏」,也可以不传 overlay、在页面层用 Sheet 承载同一份详情内容;两种方案的桌面行为一致。