Ordo UI
PatternsLayout & Shells

DetailPageFrame

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

detail-page-frame@mox-hub/patternsLayout & Shellscanonicalsrc/components/detail-page-frame.tsx
变体演示detail-page-frame
主内容区(自滚动)

Props API

Prop类型默认值说明
aiPage*string——
toolbar*(slots: { sidebar: { open: boolean; onToggle: () => void; }; }) => ReactNode——
main*ReactNode——
aside*ReactNode——
asideDefaultHidden*booleanfalse—
asideHidden*boolean——
onAsideHiddenChange*(hidden: boolean) => void——
mainWidth*PageShellVariant'reading'—
className*string——

源码

packages/patterns/src/components/detail-page-frame.tsx
/**
 * DetailPageFrame - L2 详情页双栏母版(§20.2:详情页结构自管双栏、不走 PageShell
 * 居中滚动,主栏宽度同表分发)
 *
 * 收编 task/bug/member/team 四详情页逐字重复骨架:
 * `PageShell(overflow-hidden) > SubPageToolbar > [ 主栏自滚动+居中宽档 | RightSidebar ]`
 * 侧栏开关二态(asideHidden)内聚本件,经 `toolbar({ sidebar })` render prop 下发
 * 给 SubPageToolbar 的 sidebar prop;RightSidebar 的 hidden 同步接管。
 */
import { useState, type ComponentProps, type ReactNode } from 'react';
import { cn } from '@mox-hub/ui';
import { PageShell, type PageShellVariant, VARIANT_CONTAINER_CLASSES } from './page-shell';
import { RightSidebar } from './right-sidebar';

export interface DetailPageFrameProps extends ComponentProps<'div'> {
  /** 页面标识(透传 PageShell 的 data-ai-page) */
  aiPage: string;
  /** 顶部工具栏槽:sidebar 二态由本件内聚下发(接 SubPageToolbar 的 sidebar prop) */
  toolbar: (slots: { sidebar: { open: boolean; onToggle: () => void } }) => ReactNode;
  /** 主栏内容(自滚动 + 居中宽档) */
  main: ReactNode;
  /** 右栏内容;不传则不渲染右栏(asideHidden 状态仍存在,无副作用) */
  aside?: ReactNode;
  /** 右栏初始隐藏(非受控,默认显示;与受控二选一) */
  asideDefaultHidden?: boolean;
  /** 受控:右栏是否隐藏(页面需要命令口展开右栏时用,如验收契约「编辑」入口) */
  asideHidden?: boolean;
  /** 受控:右栏隐藏态变化回调 */
  onAsideHiddenChange?: (hidden: boolean) => void;
  /** 主栏宽度档(L1 总表分发,默认 reading max-w-4xl——详情页既有基线) */
  mainWidth?: PageShellVariant;
}

export function DetailPageFrame({
  aiPage,
  toolbar,
  main,
  aside,
  asideDefaultHidden = false,
  asideHidden: asideHiddenProp,
  onAsideHiddenChange,
  mainWidth = 'reading',
  className,
  ...rest
}: DetailPageFrameProps) {
  const [internalHidden, setInternalHidden] = useState(asideDefaultHidden);
  const asideHidden = asideHiddenProp !== undefined ? asideHiddenProp : internalHidden;
  const setAsideHidden = (v: boolean | ((prev: boolean) => boolean)) => {
    const next = typeof v === 'function' ? v(asideHidden) : v;
    if (asideHiddenProp === undefined) setInternalHidden(next);
    onAsideHiddenChange?.(next);
  };
  const sidebar = { open: !asideHidden, onToggle: () => setAsideHidden((v) => !v) };

  return (
    <PageShell aiPage={aiPage} className={cn('overflow-hidden', className)}>
      {toolbar({ sidebar })}
      <div className="flex flex-1 min-h-0 overflow-hidden" {...rest}>
        <div className="flex-1 min-w-0 overflow-y-auto flex flex-col">
          <div className={cn('flex-1 flex flex-col px-page', VARIANT_CONTAINER_CLASSES[mainWidth])}>
            {main}
          </div>
        </div>
        {aside != null && (
          <RightSidebar hidden={asideHidden}>{aside}</RightSidebar>
        )}
      </div>
    </PageShell>
  );
}

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

用法说明

L2 详情页双栏母版:PageShell + SubPageToolbar + 主栏/RightSidebar 组合,侧栏开关内聚;详情页不再手写双栏骨架。