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" | — |
源码
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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
页面标题栏:唯一 h1 + 图标 + 指标胶囊 + 左右插槽;sticky 吸顶。收藏/订阅由消费方经 favorites/subscribe 槽位注入,本件不依赖路由或业务组件。