Ordo UI
PatternsLayout & Shells

AppShell

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

app-shell@mox-hub/patternsLayout & Shellscanonicalsrc/components/app-shell.tsx
变体演示app-shell
项目看板

顶栏 sticky,内容区独立滚动;侧栏折叠由 SidebarProvider 配置接管。

右栏槽与内容区并排,窄屏显隐由右栏组件自身负责。

Props API

Prop类型默认值说明
sidebar*ReactNode——
header*ReactNode——
content*ReactNode——
aside*ReactNode——
providerProps*Omit<any, "className" | "style" | "children">——
contentScroll*AppShellContentScroll'content'—
headerClassName*string——
contentClassName*string——
aiPage*string——
className*string——

源码

packages/patterns/src/components/app-shell.tsx
import type { ComponentProps, ReactNode } from 'react'
import { cn } from '@mox-hub/ui'
import { SidebarInset, SidebarProvider } from '@mox-hub/ui'

/**
 * 内容滚动策略:
 * - `content`(默认):顶栏固定,主内容区在独立滚动容器内滚动;
 * - `page`:顶栏 sticky 吸顶,整页(顶栏 + 内容)在同一滚动容器内滚动;
 * - `none`:不注入滚动,交给内容自身管理(画布/自滚动表格)。
 */
export type AppShellContentScroll = 'content' | 'page' | 'none'

export interface AppShellProps
  extends Omit<ComponentProps<'div'>, 'children' | 'content'> {
  /** 侧栏槽:通常传 `<Sidebar>…</Sidebar>`;折叠/宽度等配置放 providerProps。 */
  sidebar: ReactNode
  /** 顶栏槽:渲染在内容区上方并 sticky 吸顶;面包屑/主题切换/触发器由此注入。 */
  header?: ReactNode
  /** 主内容槽。 */
  content: ReactNode
  /** 右侧详情槽:与内容区并排;窄屏显隐由右栏组件(如 RightSidebar)自身负责。 */
  aside?: ReactNode
  /**
   * SidebarProvider 配置透传:`collapsible` / `variant` / `side` / `width` /
   * `widthIcon` / `persistence` / `storageKey` / `keyboardShortcut` / 受控开关。
   */
  providerProps?: Omit<
    ComponentProps<typeof SidebarProvider>,
    'children' | 'className' | 'style'
  >
  /** 内容滚动策略,默认 `content`;默认布局与不传 scroll 的 PageShell 一致。 */
  contentScroll?: AppShellContentScroll
  /** 顶栏容器附加类名(高度、内边距等)。 */
  headerClassName?: string
  /** 内容区附加类名。 */
  contentClassName?: string
  /** AI 页面标识:派生 data-ai-page / data-ai-component(缺省 ui.app-shell)。 */
  aiPage?: string
}

/**
 * AppShell —— 应用壳母版:侧栏 + 顶栏 + 内容区 + 可选右栏。
 *
 * 职责边界:
 * - 只负责布局与滚动链:内建 `SidebarProvider`,侧栏折叠/持久化/快捷键由既有
 *   Sidebar 体系承担,配置经 `providerProps` 透传;
 * - 顶栏固定为 sticky,内容区按 `contentScroll` 决定滚动归属;
 * - 不依赖 router / query / 业务取数:面包屑、主题切换、导航链接全部由
 *   `header` / `sidebar` 槽注入。
 */
export function AppShell({
  sidebar,
  header,
  content,
  aside,
  providerProps,
  contentScroll = 'content',
  headerClassName,
  contentClassName,
  aiPage,
  className,
  ...props
}: AppShellProps) {
  return (
    <SidebarProvider
      {...providerProps}
      data-ai-page={aiPage}
      data-ai-component={aiPage ? `${aiPage}.shell` : 'ui.app-shell'}
      data-ai-role="shell"
      className={cn('bg-content-bg text-content-text', className)}
      {...props}
    >
      {sidebar}
      <SidebarInset
        data-slot="app-shell-inset"
        className="flex h-full min-h-0 min-w-0 flex-1 flex-col overflow-hidden bg-content-bg text-content-text"
      >
        <div className="flex min-h-0 flex-1 overflow-hidden">
          <div
            data-slot="app-shell-main"
            className={cn(
              'flex min-h-0 min-w-0 flex-1 flex-col',
              contentScroll === 'page' ? 'overflow-y-auto' : 'overflow-hidden',
            )}
          >
            {header != null && (
              <div
                data-slot="app-shell-header"
                className={cn(
                  // sticky:page 滚动策略下顶栏吸附在滚动容器顶部;content 策略下
                  // 顶栏本身在滚动容器之外,sticky 只是同一套类名的无害兜底。
                  'sticky top-0 z-dropdown flex h-control-lg shrink-0 items-center gap-2 border-b border-content-border bg-content-bg px-3',
                  headerClassName,
                )}
              >
                {header}
              </div>
            )}
            <div
              data-slot="app-shell-content"
              data-scroll={contentScroll}
              className={cn(
                'flex flex-col',
                contentScroll === 'page' ? 'min-h-0' : 'min-h-0 flex-1',
                contentScroll === 'content' && 'overflow-y-auto',
                contentClassName,
              )}
            >
              {content}
            </div>
          </div>
          {aside}
        </div>
      </SidebarInset>
    </SidebarProvider>
  )
}

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

用法说明

应用壳母版:内建 SidebarProvider(配置经 providerProps 透传),slots 为 sidebar/header/content/aside;顶栏 sticky、内容区滚动策略 content(默认)/page/none;不依赖 router/query,面包屑与主题切换由 header 槽注入。

典型用法

import {
  Breadcrumb,
  Sidebar,
  SidebarContent,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarRail,
  SidebarTrigger,
} from '@mox-hub/ui'
import { AppShell, PageShell, RightSidebar } from '@mox-hub/patterns'

export function Workspace() {
  return (
    <AppShell
      aiPage="delivera.board"
      // 侧栏折叠/宽度/持久化统一交给 SidebarProvider
      providerProps={{ collapsible: 'icon', storageKey: 'delivera-sidebar' }}
      sidebar={
        <Sidebar>
          <SidebarContent>{/* SidebarGroup / SidebarMenu */}</SidebarContent>
          <SidebarRail />
        </Sidebar>
      }
      header={
        <>
          <SidebarTrigger />
          <Breadcrumb>{/* 面包屑由路由层注入 */}</Breadcrumb>
        </>
      }
      content={
        <PageShell title="项目看板" variant="wide" padded>
          {/* 页面主体 */}
        </PageShell>
      }
      aside={<RightSidebar width={360}>{/* 详情面板 */}</RightSidebar>}
    />
  )
}

滚动契约

contentScroll行为适用
content(默认)顶栏固定,内容区独立滚动大多数列表/详情页
page顶栏 sticky,顶栏与内容在同一滚动容器内长文档、需要整页滚动的页面
none不注入滚动,由内容自身管理画布、自滚动表格
  • 侧栏折叠、宽度与持久化一律放在 providerProps(透传 SidebarProvider),Sidebar 只负责结构。
  • 顶栏高度默认 h-control-lg,可用 headerClassName 覆写;内容区间距用 contentClassName。
  • 窄屏下侧栏自动切换为 Sheet(Sidebar 内建);右栏的窄屏行为由右栏组件(如 RightSidebar)负责。