Ordo UI
PatternsApp Patterns

PageHeader

@mox-hub/patterns 模式 · App Patterns · canonical

page-header@mox-hub/patternsApp Patternscanonicalsrc/components/page-header.tsx
变体演示page-header

支付服务

任务12风险2
页面内容区

Props API

Prop类型默认值说明
title*ReactNode——
actions*ReactNode——
metrics*PageHeaderMetric[]——
favorites*ReactNode——
subscribe*ReactNode——
className*string——
aiId*string——
icon*IconComponent——
iconColor*string"text-primary"—

源码

packages/patterns/src/components/page-header.tsx
import { isValidElement, type ReactNode } from "react";
import { cn } from "@mox-hub/ui";
import type { IconComponent } from "../lib/types";

export type { IconComponent };

export interface PageHeaderMetric {
  id?: string;
  label: ReactNode;
  value: ReactNode;
  tone?: "default" | "success" | "warning" | "danger";
}

/** 计数胶囊:浅色底 + 描边 + 状态点,尺寸更小 */
const METRIC_TONE_CLASS: Record<NonNullable<PageHeaderMetric["tone"]>, { pill: string; dot: string }> = {
  default: { pill: "border-border bg-muted/60 text-muted-foreground", dot: "bg-muted-foreground/70" },
  success: { pill: "border-accent-green/40 bg-accent-green-light text-accent-green", dot: "bg-accent-green" },
  warning: { pill: "border-accent-yellow/50 bg-accent-yellow-light text-accent-yellow", dot: "bg-accent-yellow" },
  danger: { pill: "border-accent-red/40 bg-accent-red-light text-accent-red", dot: "bg-accent-red" },
};

export interface PageHeaderProps {
  title: ReactNode;
  actions?: ReactNode;
  /** 最右侧计数器标签(文本 + 数字),如任务数量、项目健康度 */
  metrics?: PageHeaderMetric[];
  /**
   * 标题右侧收藏槽位:由业务调用方自行构造节点,不传则不渲染。
   */
  favorites?: ReactNode;
  /**
   * 收藏槽位右侧订阅槽位:由业务调用方自行构造节点,不传则不渲染。
   */
  subscribe?: ReactNode;
  className?: string;
  aiId?: string;
  icon?: IconComponent;
  iconColor?: string;
}

/** 从 ReactNode 提取纯文本,作为收藏到侧边栏时的页面名称(导出供业务调用方构造收藏槽位 label) */
export function nodeToText(node: ReactNode): string {
  if (node === null || node === undefined || typeof node === "boolean") return "";
  if (typeof node === "string" || typeof node === "number") return String(node);
  if (Array.isArray(node)) return node.map(nodeToText).join("");
  if (isValidElement(node)) {
    const props = node.props as { children?: ReactNode };
    return nodeToText(props.children);
  }
  return "";
}

/**
 * PageHeader —— 页面标题栏(唯一 h1 + 图标 + 指标胶囊 + 左右插槽,sticky 吸顶)。
 *
 * 收藏/订阅由消费方经 favorites / subscribe 槽位注入;本件不依赖业务组件或路由。
 */
export function PageHeader({
  title,
  actions,
  metrics,
  favorites,
  subscribe,
  className,
  aiId,
  icon: Icon,
  iconColor = "text-primary",
}: PageHeaderProps) {
  return (
    <header
      className={cn(
        // sticky:页面滚动时标题行吸附在滚动容器顶部(内容区从其下滚过)
        "sticky top-0 z-dropdown flex h-control-lg w-full shrink-0 items-center gap-2 border-b border-border bg-background px-page",
        className,
      )}
      data-ai-component={aiId ? `${aiId}.header` : "ui.page-header"}
      data-ai-role="content"
    >
      {Icon ? <Icon className={cn("size-5 shrink-0", iconColor)} strokeWidth={1.75} /> : null}
      <div className="flex min-w-0 flex-1 items-center gap-2">
        <h1 className="m-0 min-w-0 truncate font-heading text-heading-3 font-semibold leading-tight text-foreground">{title}</h1>
        {favorites}
        {subscribe}
        {metrics && metrics.length > 0 ? (
          <div className="flex min-w-0 shrink items-center gap-2 overflow-x-auto">
            {metrics.map((metric, index) => {
              const tone = METRIC_TONE_CLASS[metric.tone ?? "default"];
              return (
                <span
                  key={metric.id ?? index}
                  className={cn(
                    "inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium whitespace-nowrap",
                    tone.pill,
                  )}
                >
                  <span className={cn("size-1.5 shrink-0 rounded-full", tone.dot)} />
                  <span>{metric.label}</span>
                  <span className="font-semibold tabular-nums">{metric.value}</span>
                </span>
              );
            })}
          </div>
        ) : null}
      </div>
      {actions ? (
        <div className="flex min-w-0 shrink items-center gap-2 overflow-x-auto">
          {actions}
        </div>
      ) : null}
    </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。

用法说明

页面标题栏:唯一 h1 + 图标 + 指标胶囊 + 左右插槽;sticky 吸顶。收藏/订阅由消费方经 favorites/subscribe 槽位注入,本件不依赖路由或业务组件。