深色模式

Nex UI 支持 light 和 dark 两种主题，默认为 light。

仅用深色模式

您可以向 NexUIProvider 添加 defaultMode: 'dark' 属性使应用程序默认使用深色主题，而不用考虑用户的偏好。


import { NexUIProvider } from '@nex-ui/react'
 
export default function App() {
  return (
    <NexUIProvider defaultMode='dark'>
      <main>This app is using the dark mode</main>
    </NexUIProvider>
  )
}

覆盖深色模式下的颜色

如果您想要变更深色模式下的预设颜色，可以通过 semanticTokens 设置。查看 semanticTokens了解更多信息。


import { defineTheme } from '@nex-ui/react'
 
defineTheme({
  semanticTokens: {
    colors: {
      blue: {
        outlined: {
          _dark: '#fff',
        },
      },
    },
  },
})

系统偏好

一些用户可能会通过操作系统，在系统层面设置对浅色或深色模式的偏好。NexUI 内置支持该特性，设置 defualtMode: 'system' 即可。


import { NexUIProvider } from '@nex-ui/react'
 
export default function App() {
  return (
    <NexUIProvider defaultMode='system'>
      <main>...</main>
    </NexUIProvider>
  )
}

访问用户偏好

另外，您可以通过 useColorScheme hook 访问用户的系统偏好。


import { NexUIProvider, useColorScheme } from '@nex-ui/react'
 
export default function App() {
  const { systemColorScheme } = useColorScheme()
 
  return (
    <NexUIProvider defaultMode='system'>
      <main>System preference: {systemColorScheme}</main>
    </NexUIProvider>
  )
}

切换主题模式

可使用 useColorScheme hook 来读取和更新主题模式。


import { NexUIProvider, useColorScheme, Button } from '@nex-ui/react'
 
export default function App() {
  const { mode, setMode } = useColorScheme()
 
  return (
    <NexUIProvider defaultMode='system'>
      <Button onClick={() => setMode('light')}>Light</Button>
      <Button onClick={() => setMode('dark')}>Dark</Button>
      <Button onClick={() => setMode('system')}>System</Button>
    </NexUIProvider>
  )
}

防止 SSR 闪烁

为了防止深色模式在服务器渲染初次加载时出现闪烁，您可以添加 InitColorSchemeScript 组件，并且必须保证 defaultMode、modeStorageKey、colorSchemeSelector、colorSchemeNode 属性设置与传递给 NexUIProvider 组件相同的值。


import { InitColorSchemeScript } from '@nex-ui/react'
 
<InitColorSchemeScript defaultMode="dark">

深色模式下的样式设计

在 sx 属性中使用 _dark 为组件设置深色模式下的样式，_light 为组件设置浅色模式的样式，_DEFAULT 为组件的默认样式。


import { Box } from '@nex-ui/react'
 
export default function App() {
  return (
    <Box
      sx={{
        color: {
          _DEFAULT: 'black',
          _light: 'black',
          _dark: 'white',
        },
      }}
    >
      Box
    </Box>
  )
}

或者以 _dark、_light 为 CSS 选择器，设置一组 CSS 属性：


<Box
  sx={{
    _light: {
      color: 'black',
      bg: 'green.500',
    },
    _dark: {
      color: 'white',
      bg: 'green.600',
    },
  }}
>
  Box
</Box>

上述两种方式意味着可以把 _light 和 _dark 当作 Selectors 去使用。

API

InitColorSchemeScriptProps

Prop	Type	Default	Description
defaultMode	'light'\|'dark'\|'system'	'system'	默认的主题模式。
modeStorageKey	string	'nui-color-scheme'	用于在 localStorage 中存储主题模式的键。
colorSchemeSelector	'data'\|'class'\|string	'data-nui-color-scheme'	应用 CSS 主题变量和组件样式的方法。支持传入 `data-*` 字符串。
colorSchemeNode	Element	document.documentElement	用于附加 color-scheme 属性的节点。

useColorScheme

useColorScheme() => ColorSchemeContext

mode: string 用户选择的主题模式。
setMode: (mode?: Mode) => void - 用于设置主题模式的函数。该主题模式会保存到内部状态和 localStorage 中，如果 mode 为 null ，将重置为默认主题模式。
systemColorScheme - 当 mode: system 时，返回系统用户偏好。