主题

在根布局统一配置主题，让每个页面在渲染前读取同一份偏好。ThemeToggle 只负责修改共享状态，不能代替 ThemeProvider 或 ThemeScript。

适用场景

需要保存浅色或深色主题偏好的应用
页头上的主题切换

在根布局中用 ThemeProvider 包裹页面内容，管理主题状态；将 ThemeScript 放进 head，在内容显示前应用主题。ThemeToggle 用于切换主题，通常放在页头。

用法

src/app/layout.tsx

TSX

import { ThemeProvider } from 'blackwork'
import { ThemeScript } from 'blackwork/rsc'

const RootLayout = ({ children }: React.PropsWithChildren) => {
  return (
    <html lang="zh-CN" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}

export default RootLayout

用法

示例

下拉菜单

API 参考

属性	类型	默认值	说明
`defaultTheme`	`"light" \| "dark"`	`"dark"`	ThemeProvider 的初始主题。
`storageKey`	`string`	`"blackwork-theme"`	ThemeProvider 保存主题偏好时使用的 localStorage 键名。
`mode`	`"button" \| "dropdown"`	`"button"`	ThemeToggle 的交互模式。
`options`	`ThemeToggleOption[]`	—	ThemeToggle 的自定义标签和图标。
`ariaLabel`	`string`	—	ThemeToggle 的无障碍名称。

说明

默认主题是 dark。
主题偏好保存在 localStorage 中，默认键名为 blackwork-theme。
ThemeScript 和 ThemeProvider 的 storageKey、defaultTheme 必须一致。
本站已在根布局中配置 ThemeProvider，上面的预览直接使用该主题状态。
需要跟随系统主题时，将 system 加入切换选项，并明确设置默认值。