PatternsApp Patterns
SubPageToolbar
@mox-hub/patterns 模式 · App Patterns · canonical
sub-page-toolbar@mox-hub/patternsApp Patternscanonicalsrc/components/sub-page-toolbar.tsx变体演示sub-page-toolbar
3/12
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| aiId* | string | — | — |
| className* | string | — | — |
| onBack* | () => void | — | — |
| backLabel* | string | — | — |
| breadcrumbs* | SubPageBreadcrumb[] | — | — |
| titleIcon* | ReactNode | — | — |
| tabs* | { value: string; onChange: (value: string) => void; items: SubPageTabItem[]; } | — | — |
| pager* | SubPagePager | — | — |
| actions* | ReactNode | — | — |
| sidebar* | SubPageSidebarToggle | — | — |
| renderLink* | (item: SubPageBreadcrumb, className: string, children: ReactNode) => ReactNode | — | — |
| labels* | Partial<SubPageToolbarLabels> | — | — |
源码
import type { ReactNode } from "react";
import {
ArrowLeft,
ChevronLeft,
ChevronRight,
PanelRight,
PanelRightClose,
type LucideIcon,
} from "lucide-react";
import { cn } from "@mox-hub/ui";
import { usePatternLabels } from "../lib/i18n";
import { HeaderActionButton } from "./header-action-button";
import { SegmentedControl, type SegmentedTone } from "@mox-hub/ui/components/segmented-control";
export interface SubPageBreadcrumb {
label: ReactNode;
to?: string;
}
export interface SubPageTabItem {
value: string;
label: string;
icon?: LucideIcon;
/** 激活滑块高亮色调(页面按需传入) */
tone?: SegmentedTone;
}
export interface SubPagePager {
hasPrev: boolean;
hasNext: boolean;
onPrev: () => void;
onNext: () => void;
/** 当前位置计数,如 "3/12",缺省显示 "—" */
position?: ReactNode;
}
export interface SubPageSidebarToggle {
open: boolean;
onToggle: () => void;
}
export interface SubPageToolbarLabels {
back: string;
previous: string;
next: string;
breadcrumb: string;
showSidebar: string;
hideSidebar: string;
}
const DEFAULT_LABELS: SubPageToolbarLabels = {
back: "返回",
previous: "上一个",
next: "下一个",
breadcrumb: "面包屑",
showSidebar: "显示侧边栏",
hideSidebar: "隐藏侧边栏",
};
interface SubPageToolbarProps {
aiId?: string;
className?: string;
/** 最左返回按钮;缺省回落浏览器 history.back()(库内不依赖 router) */
onBack?: () => void;
backLabel?: string;
/** 层级面包屑,ChevronRight 分隔,可点项由 renderLink 注入(缺省 <a href>),末项高亮 */
breadcrumbs?: SubPageBreadcrumb[];
/** 面包屑链接渲染器:主仓传 router Link;缺省渲染 <a href={item.to}> */
renderLink?: (item: SubPageBreadcrumb, className: string, children: ReactNode) => ReactNode;
/** 面包屑末项实体图标(F 类 J11/F2.5②):icon 必须取自 entity-icons 唯一源(与 L1 PageHeader 同源),禁页面自选 */
titleIcon?: ReactNode;
/** 居中子页签(SegmentedControl rect 滑块,与 ToolbarRow 同款) */
tabs?: {
value: string;
onChange: (value: string) => void;
items: SubPageTabItem[];
};
/** 翻页器:同集合内浏览上一/下一实体(如项目内任务) */
pager?: SubPagePager;
/** 自定义按钮组(HeaderActionButton 实例 / Badge 等) */
actions?: ReactNode;
/** 最后一个固定按钮:展开/收起右侧边栏;无右侧面板的页面不传 */
sidebar?: SubPageSidebarToggle;
labels?: Partial<SubPageToolbarLabels>;
}
/**
* 二级子页面工具栏:返回按钮 + 面包屑(左)、居中子页签(中)、
* 翻页器 + 自定义按钮组 + 侧栏开关(右)。单行、无上下分界线,布局与 ToolbarRow 一致。
*/
export function SubPageToolbar({
aiId,
className,
onBack,
backLabel,
breadcrumbs,
titleIcon,
tabs,
pager,
actions,
sidebar,
renderLink,
labels,
}: SubPageToolbarProps) {
const D = usePatternLabels("subPageToolbar", DEFAULT_LABELS);
const L = { ...D, ...labels };
const handleBack =
onBack ??
(() => {
if (typeof window !== "undefined") window.history.back();
});
return (
<header
className={cn(
"grid w-full shrink-0 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 px-6 py-2 md:px-7",
className,
)}
data-ai-component={aiId ? `${aiId}.sub-page-toolbar` : "ui.sub-page-toolbar"}
data-ai-role="nav"
>
<div className="flex min-w-0 items-center gap-1.5">
<HeaderActionButton
variant="ghost"
icon={ArrowLeft}
iconClassName="rtl:-scale-x-100"
label={backLabel ?? L.back}
onClick={handleBack}
data-ai-component={aiId ? `${aiId}.back-button` : undefined}
data-ai-action={aiId ? `${aiId}.back-button.click` : undefined}
/>
{breadcrumbs && breadcrumbs.length > 0 ? (
<nav className="flex min-w-0 items-center gap-1 text-xs" aria-label={L.breadcrumb}>
{breadcrumbs.map((crumb, index) => {
const isLast = index === breadcrumbs.length - 1;
return (
<span key={index} className="flex min-w-0 items-center gap-1">
{index > 0 ? <ChevronRight className="size-3 shrink-0 text-muted-foreground/60 rtl:-scale-x-100" aria-hidden /> : null}
{isLast && titleIcon ? <span className="flex shrink-0">{titleIcon}</span> : null}
{crumb.to && !isLast ? (
renderLink ? (
renderLink(
crumb,
"truncate text-muted-foreground transition-colors hover:text-foreground",
crumb.label,
)
) : (
<a
href={crumb.to}
className="truncate text-muted-foreground transition-colors hover:text-foreground"
>
{crumb.label}
</a>
)
) : (
<span className={cn("truncate", isLast ? "font-medium text-foreground" : "text-muted-foreground")}>
{crumb.label}
</span>
)}
</span>
);
})}
</nav>
) : null}
</div>
{tabs ? (
<div className="justify-self-center">
<SegmentedControl
variant="rect"
value={tabs.value}
onChange={tabs.onChange}
options={tabs.items.map((item) => {
const Icon = item.icon;
return {
value: item.value,
label: item.label,
icon: Icon ? <Icon className="size-3.5" strokeWidth={1.75} /> : undefined,
tone: item.tone,
};
})}
/>
</div>
) : (
<div />
)}
<div className="flex items-center justify-end gap-2">
{pager ? (
<div className="flex items-center gap-1" data-ai-component={aiId ? `${aiId}.pager` : undefined}>
<HeaderActionButton
variant="ghost"
icon={ChevronLeft}
iconClassName="rtl:-scale-x-100"
label={L.previous}
disabled={!pager.hasPrev}
onClick={pager.onPrev}
/>
<span className="min-w-12 text-center text-xs tabular-nums text-muted-foreground">
{pager.position ?? "—"}
</span>
<HeaderActionButton
variant="ghost"
icon={ChevronRight}
iconClassName="rtl:-scale-x-100"
label={L.next}
disabled={!pager.hasNext}
onClick={pager.onNext}
/>
</div>
) : null}
{actions}
{sidebar ? (
<HeaderActionButton
variant="outline"
icon={sidebar.open ? PanelRightClose : PanelRight}
label={sidebar.open ? L.hideSidebar : L.showSidebar}
aria-pressed={sidebar.open}
onClick={sidebar.onToggle}
data-ai-component={aiId ? `${aiId}.sidebar-toggle` : undefined}
data-ai-action={aiId ? `${aiId}.sidebar-toggle.click` : undefined}
/>
) : null}
</div>
</header>
);
}
可访问性与 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。
用法说明
二级子页工具栏:返回 + 面包屑 + 居中页签 + 翻页 + 侧栏开关;面包屑链接经 renderLink 注入(缺省 <a>),返回缺省 history.back()。