布局

这些是 Blackwork 的页面框架：粘性页头、统一的内容边距、短页脚。文章需要侧栏或目录时，再加上圣杯分栏。

注意

不要在 Next.js App Router 树里使用 RootLayout。它会自己渲染 html 和 body。在 Next.js 里，把 ThemeScript 放到 head，用 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`	即使数组有内容也隐藏社交链接。
`languageToggle`	`ReactNode`	—	LanguageToggle 或自定义语言控件的插槽。
`themeToggle`	`ReactNode`	—	ThemeToggle 的插槽。
`children`必填	`ReactNode`	—	页头左侧的品牌和主导航。

主栏

主内容

Page content uses the shared content gutter.

LayoutMain

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

页脚

圣杯分栏

没有总包裹组件。把 HolyGrailAside 和 HolyGrailContent 放进一行 flex。侧栏在 lg 以下会隐藏。

圣杯布局

Article

HolyGrailAside

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

RootLayout

RootLayout 是完整文档壳：html、带 ThemeScript 的 head、带 ThemeProvider 的 body。

注意

只有你拥有整份文档时才用，不要嵌进已有的 App Router 布局。

RootLayout

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

说明

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