布局

单栏内容页从 LayoutHeader、LayoutMain 和 LayoutFooter 开始；只有导航或目录需要独立列时，才加入圣杯分栏。

博客和文档站通常需要页头、正文和页脚。Blackwork 的布局组件为这些区域提供统一的边距，页头默认支持吸顶。文章页需要导航和目录时，可以再加入左右侧栏。

注意

Blackwork 的 RootLayout 会渲染 html 和 body，不能嵌入已有的 Next.js App Router 布局。Next.js 项目应在自己的根布局中配置 ThemeScript 和 ThemeProvider，再组合页头、正文和页脚，完整示例见下文。

适用场景

博客、文档站或其他需要统一边距的内容页
左侧展示品牌、右侧放置站点操作的吸顶页头
左侧导航、右侧目录的文章页

主题切换的配置见主题，语言切换和社交链接的用法见小工具。

Next.js 页面布局

服务端组件

LayoutMain 和 LayoutFooter 可以从 blackwork/rsc 在服务端渲染。LayoutHeader 要从 blackwork 引入，因为它承载客户端操作。

src/app/layout.tsx

TSX

import { LayoutHeader, ThemeProvider, ThemeToggle } from 'blackwork'
import { LayoutFooter, LayoutMain, ThemeScript } from 'blackwork/rsc'

const RootLayout = ({ children }: React.PropsWithChildren) => {
  return (
    <html lang="zh-CN" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body className="flex min-h-dvh flex-col">
        <ThemeProvider>
          <LayoutHeader themeToggle={<ThemeToggle />}>Blackwork</LayoutHeader>
          <LayoutMain>{children}</LayoutMain>
          <LayoutFooter>© Blackwork</LayoutFooter>
        </ThemeProvider>
      </body>
    </html>
  )
}

export default RootLayout

页头

通过 children 传入品牌和主导航，显示在页头左侧。社交链接、语言切换和主题切换各有对应的属性，显示在右侧。

页头

Blackwork

LayoutHeader

属性	类型	默认值	说明
`socialLinks`	`SocialLinkProps[]`	—	显示在页头右侧的图标按钮。
`socialLinksVisible`	`boolean`	`true`	设为 false 时隐藏社交链接，即使数组中已有链接。
`languageToggle`	`ReactNode`	—	LanguageToggle 或自定义语言控件的插槽。
`themeToggle`	`ReactNode`	—	ThemeToggle 的插槽。
`children`必填	`ReactNode`	—	页头左侧的品牌和主导航。

主栏

主内容

The main content has consistent spacing on both sides.

LayoutMain

属性	类型	默认值	说明
`fullscreen`	`boolean`	`false`	移除内容边距和垂直内边距，用于铺满页面。
`asChild`	`boolean`	`false`	将布局类名合并到子节点，不再额外渲染 main 元素。

页脚

圣杯分栏

圣杯布局将正文放在中间，两侧用于导航或目录。将 HolyGrailAside 和 HolyGrailContent 放入横向 flex 容器即可组合，侧栏在小于 lg 断点时隐藏。

圣杯布局

Article

HolyGrailAside

属性	类型	默认值	说明
`smaller`	`boolean`	`false`	使用较窄的栏宽，通常用于左侧导航；默认宽度适合目录。
`asChild`	`boolean`	`false`	将分栏类名合并到子节点。

RootLayout

RootLayout 适用于由应用直接渲染完整 HTML 文档的场景，包含 html、带 ThemeScript 的 head，以及带 ThemeProvider 的 body。Next.js 项目使用上面的页面布局示例即可。

RootLayout

属性	类型	默认值	说明
`lang`	`string`	`"en"`	html 的 lang，使用 en 或 zh-CN 等 BCP 47 标签。
`metadata`	`ReactNode`	—	显示在 head 内、ThemeScript 后面的额外节点。
`className`	`string`	—	应用于 body 的类名。

说明

LayoutHeader 默认吸顶。在嵌套预览中使用或不需要吸顶时，可通过 className 覆盖定位样式。
LayoutMain fullscreen 会去掉统一边距，适合铺满屏幕的落地页。
HolyGrailAside smaller 是较窄的导航栏，默认宽度适合目录。

玻璃外观

页头需要覆盖在页面背景上时，为 LayoutHeader 设置 appearance="glass"。共享主题配置见液态玻璃。