项目看板
待办 8
进行中 3
已完成 21
@mox-hub/patterns 模式 · Layout & Shells · canonical
page-shell@mox-hub/patternsLayout & Shellscanonicalsrc/components/page-shell.tsx| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| children* | ReactNode | — | — |
| className* | string | — | — |
| variant* | PageShellVariant | "full" | — |
| padded* | boolean | — | — |
| scroll* | PageShellScroll | "none" | — |
| contentClassName* | string | — | — |
| aiPage* | string | — | — |
| title* | ReactNode | — | — |
| icon* | LucideIcon | — | — |
| iconColor* | string | — | — |
| actions* | ReactNode | — | — |
| metrics* | PageHeaderMetric[] | — | — |
| favorites* | ReactNode | — | — |
| subscribe* | ReactNode | — | — |
import type { HTMLAttributes, ReactNode } from "react";
import type { LucideIcon } from "lucide-react";
import { cn } from "@mox-hub/ui";
import { PageHeader, type PageHeaderMetric } from "./page-header";
export type PageShellVariant = "full" | "wide" | "standard" | "reading";
/**
* 页面滚动归属:
* - `none`(默认):不注入 overflow,保持既有布局,由消费方/外层容器决定滚动;
* - `page`:PageShell 外层滚动,标题栏 sticky 吸顶(列表页、长文档);
* - `content`:内容区滚动,标题栏固定(画布页、固定工具栏 + 自滚动内容)。
*/
export type PageShellScroll = "page" | "content" | "none";
/** L1 主栏宽度四档总表(F1.3)——详情母版 DetailPageFrame 同表分发(§20.2),勿在别处手写 */
export const VARIANT_CONTAINER_CLASSES: Record<PageShellVariant, string> = {
full: "w-full",
wide: "w-full max-w-7xl mx-auto",
standard: "w-full max-w-5xl mx-auto",
reading: "w-full max-w-4xl mx-auto",
};
const VARIANT_PADDING_CLASSES: Record<PageShellVariant, string> = {
// 审计 P2-10:四档统一消费 --spacing-page,页头/工具栏/正文同一条左右基线。
full: "px-page py-4",
wide: "px-page py-section sm:py-8",
standard: "px-page py-section sm:py-8",
reading: "px-page py-8 sm:py-10",
};
export interface PageShellProps {
children: ReactNode;
className?: string;
/**
* 页面规格变体(F 类 F1.3 主栏宽度四档总表;DESIGN.md §3.4 转正):
* - 'full' (默认): 全宽高密,适合看板、工单列表、甘特图
* - 'wide': 聚合宽档(max-w-7xl 居中),适合聚合型详情、仪表盘、多卡片网格
* - 'standard': 舒适限制(max-w-5xl 居中),适合设置页、表单配置
* - 'reading': 阅读聚焦(max-w-4xl),适合文档详情阅读、帮助中心、日志审阅
*/
variant?: PageShellVariant;
/**
* 是否自动对内容区注入标准页面内边距:
* - standard: 默认为 true
* - reading: 默认为 true
* - full: 默认为 false(保持全宽自管画布兼容性)
*/
padded?: boolean;
/** 内容包裹区额外类名 */
contentClassName?: string;
/**
* 滚动归属(默认 `none`,不改变既有布局):
* - `page`:整页滚动,标题栏 sticky 吸顶;
* - `content`:内容区自滚动,标题栏固定;
* - `none`:不注入 overflow,由消费方自行管理。
*/
scroll?: PageShellScroll;
aiPage?: string;
title?: ReactNode;
icon?: LucideIcon;
iconColor?: string;
actions?: ReactNode;
metrics?: PageHeaderMetric[];
/**
* 标题右侧收藏/订阅槽位:由业务调用方构造节点,透传给内嵌 PageHeader。
*/
favorites?: ReactNode;
subscribe?: ReactNode;
}
/**
* PageShell —— 页面壳:可选标题栏 + 四档主栏宽度 + 可选内边距。
*
* 详情页双栏母版用 detail-page-frame(后续批迁入),不在本组件内实现。
*/
export function PageShell({
children,
className,
variant = "full",
padded,
scroll = "none",
contentClassName,
aiPage,
title,
icon,
iconColor,
actions,
metrics,
favorites,
subscribe,
}: PageShellProps) {
const hasHeader = Boolean(title || icon || actions || metrics);
const shouldPad = padded ?? (variant !== "full");
return (
<div
className={cn(
"flex flex-1 min-h-0 flex-col bg-content-bg text-content-text",
// page:整页滚动;标题栏 PageHeader 自带 sticky,吸附在本滚动容器顶部。
scroll === "page" && "overflow-y-auto",
className,
)}
data-ai-page={aiPage}
data-ai-component={aiPage ? `${aiPage}.shell` : "ui.page-shell"}
data-ai-role="page"
data-scroll={scroll}
>
{hasHeader && (
<PageHeader
title={title ?? ""}
icon={icon}
iconColor={iconColor}
actions={actions}
metrics={metrics}
favorites={favorites}
subscribe={subscribe}
aiId={aiPage}
className="border-content-border"
/>
)}
<div className="flex min-h-0 flex-1 flex-col">
<div
className={cn(
// min-h-0 与外层包装一致:flex 压缩链必须逐层贯通,否则内容高度
// 反向撑破视口(自管页面溢出被裁、文档流页面撑高整页滚动)
"flex min-h-0 flex-col flex-1",
// content:内容区自滚动,标题栏在滚动容器之外保持固定。
scroll === "content" && "overflow-y-auto",
VARIANT_CONTAINER_CLASSES[variant],
shouldPad && VARIANT_PADDING_CLASSES[variant],
contentClassName,
)}
>
{children}
</div>
</div>
</div>
);
}
export interface PageBodyProps extends HTMLAttributes<HTMLDivElement> {
children?: ReactNode;
variant?: PageShellVariant;
padded?: boolean;
}
/** 供页面内部局部区域按规格包裹的轻量容器 */
export function PageBody({
children,
variant = "full",
padded = true,
className,
...props
}: PageBodyProps) {
return (
<div
className={cn(
"flex flex-col flex-1",
VARIANT_CONTAINER_CLASSES[variant],
padded && VARIANT_PADDING_CLASSES[variant],
className,
)}
{...props}
>
{children}
</div>
);
}
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。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。页面壳(从 @mox-hub/patterns 导入;ui 根入口不含页面骨架):可选标题栏 + 四档主栏宽度(full/wide/standard/reading)+ 可选内边距;scroll=page(整页滚动、标题栏 sticky)/content(内容区自滚动、标题栏固定)/none(默认,不注入 overflow);详情双栏母版用 detail-page-frame。
PageShell 默认 scroll="none":不注入任何 overflow,保持既有页面行为。需要明确「谁负责滚动」时按页面类型选择:
scroll | 滚动容器 | 典型页面 |
|---|---|---|
none(默认) | 消费方/外层容器 | 既有页面,行为不变 |
page | PageShell 外层;标题栏 sticky 吸顶 | 列表页、长文档 |
content | 内容区;标题栏固定 | 画布页、固定工具栏 + 自滚动内容 |
列表页整页滚动:
<PageShell scroll="page" title="项目列表" variant="wide">
{/* 长列表:随整页一起滚动,标题栏吸顶 */}
</PageShell>画布页内容区自滚动(外层高度需确定,如 AppShell 的 content 槽):
<PageShell scroll="content" title="流程画布" variant="full" className="min-h-0">
<div className="min-h-0 flex-1">{/* 画布/工作台内容 */}</div>
</PageShell>min-h-0 / flex-1),否则 scroll="content" 的内容区不会产生滚动。PageHeader)本身已带 sticky top-0:scroll="page" 时吸附在整页滚动容器顶部,scroll="content" 时位于内容滚动容器之外。