快速开始

常见路径是：安装 blackwork、引入一个样式入口、配置根布局主题，再渲染第一个 Button。其余指南都基于这套配置。

Blackwork 提供博客和文档站常用的布局、主题和交互组件。本站和博客 chengpeiquan.com 都使用这套组件，可以作为实际页面的参考。

下面从安装和样式配置开始，再以 Next.js App Router 为例搭建一个带主题切换的页面。

环境要求

需要 React 19+ 和 Tailwind CSS v4。

新建文档站可以参考文档站指南，了解模板用途、创建命令和部署步骤。

安装

Bash

pnpm add blackwork

使用 blackwork/form 构建表单时，还需要安装 TanStack Form：

Bash

pnpm add @tanstack/react-form

引入样式

在应用样式表里引入 Tailwind 和 Blackwork：

src/app/globals.css

CSS

@import 'tailwindcss';
@import 'blackwork/tailwind.css';

如果要覆盖默认无衬线字体，设置 --blackwork-font-sans：

src/app/globals.css

CSS

:root {
  --blackwork-font-sans: 'Your Font', sans-serif;
}

如果只需要主题变量和全局样式，不需要 Tailwind 扫描 Blackwork 组件的类名，可以改用以下入口：

CSS

@import 'blackwork/theme.css';
@import 'blackwork/ui-globals.css';

接入 Next.js

在根布局引入样式，用 ThemeProvider 管理主题。ThemeScript 放在 head 中，让页面在显示内容前应用主题，避免浅色和深色之间的闪烁。下面的布局包含页头、正文、页脚和主题切换按钮。

src/app/layout.tsx

TSX

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

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 />}>我的网站</LayoutHeader>
          <LayoutMain>{children}</LayoutMain>
          <LayoutFooter>© 我的网站</LayoutFooter>
        </ThemeProvider>
      </body>
    </html>
  )
}

export default RootLayout

第一个组件

src/app/page.tsx

TSX

import { Button } from 'blackwork'

const Page = () => {
  return <Button>开始使用</Button>
}

export default Page

服务端组件

Button、浮层和大部分交互组件从 blackwork 引入。可以在服务端渲染的布局和基础组件从 blackwork/rsc 引入。

页面运行后，先在浅色和深色主题下各检查一次，再继续查看布局、主题和小工具的用法。组件总览列出了其他可用组件，也说明了参考 shadcn/ui 示例时需要注意的 API 差异。