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 | number | 360 | — |
| overlay* | boolean | false | — |
| overlayOpen* | boolean | — | — |
| defaultOverlayOpen* | boolean | false | — |
| onOverlayOpenChange* | (open: boolean) => void | — | — |
| overlayLabel* | string | — | — |
| overlayTitle* | string | — | — |
| overlayDescription* | string | — | — |
| overlayTriggerClassName* | string | — | — |
| className* | string | — | — |
| children* | ReactNode | — | — |
源码
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/translatorprops,其次用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的rightSidebarsection 统一提供。
若产品更希望「窄屏换用独立 Sheet 而非右栏」,也可以不传 overlay、在页面层用 Sheet 承载同一份详情内容;两种方案的桌面行为一致。