项目看板
顶栏 sticky,内容区独立滚动;侧栏折叠由 SidebarProvider 配置接管。
右栏槽与内容区并排,窄屏显隐由右栏组件自身负责。
@mox-hub/patterns 模式 · Layout & Shells · canonical
app-shell@mox-hub/patternsLayout & Shellscanonicalsrc/components/app-shell.tsx| 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 | — | — |
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>
)
}
: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。应用壳母版:内建 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。RightSidebar)负责。