Ordo UI
PatternsLayout & Shells

PageShell

@mox-hub/patterns 模式 · Layout & Shells · canonical

page-shell@mox-hub/patternsLayout & Shellscanonicalsrc/components/page-shell.tsx
变体演示page-shell

项目看板

待办 8
进行中 3
已完成 21

Props API

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

源码

packages/patterns/src/components/page-shell.tsx
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>
  );
}

可访问性与 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。

用法说明

页面壳(从 @mox-hub/patterns 导入;ui 根入口不含页面骨架):可选标题栏 + 四档主栏宽度(full/wide/standard/reading)+ 可选内边距;scroll=page(整页滚动、标题栏 sticky)/content(内容区自滚动、标题栏固定)/none(默认,不注入 overflow);详情双栏母版用 detail-page-frame。

滚动契约

PageShell 默认 scroll="none":不注入任何 overflow,保持既有页面行为。需要明确「谁负责滚动」时按页面类型选择:

scroll滚动容器典型页面
none(默认)消费方/外层容器既有页面,行为不变
pagePageShell 外层;标题栏 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>
  • flex 压缩链要逐层贯通(min-h-0 / flex-1),否则 scroll="content" 的内容区不会产生滚动。
  • 标题栏(PageHeader)本身已带 sticky top-0:scroll="page" 时吸附在整页滚动容器顶部,scroll="content" 时位于内容滚动容器之外。