Ordo UI
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>——

源码

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

用法说明

二级子页工具栏:返回 + 面包屑 + 居中页签 + 翻页 + 侧栏开关;面包屑链接经 renderLink 注入(缺省 <a>),返回缺省 history.back()。