主题

主题化是设计用户界面 (UI) 的关键要素。它能够在整个应用程序中应用一致的美观，从而增强用户体验并保持视觉统一性。

在 NextUI 中，我们使用 TailwindCSS 插件来简化和灵活地自定义主题。此插件基于 tw-colors 插件（由 L-Blondy 开发），它允许您自定义配色方案、布局配置以及应用程序不同组件中的更多内容。

什么是主题？

在 NextUI 的上下文中，主题是一组预定义的颜色、布局属性和其他 UI 元素，您可以将其一致地应用于整个应用程序。主题确保视觉一致性，丰富用户体验，并简化应用程序外观和感觉的管理和更新。

设置

使用 NextUI 主题功能的第一步是将 nextui 插件添加到 tailwind.config.js 文件中。以下是执行此操作的一个示例

注意：如果您使用的是 pnpm 和单一仓库架构，请确保您指向 ROOT node_modules

// tailwind.config.js
const {nextui} = require("@nextui-org/react");

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ...
    // make sure it's pointing to the ROOT node_module
    "./node_modules/@nextui-org/theme/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  darkMode: "class",
  plugins: [nextui()],
};

用法

将插件添加到 tailwind.config.js 文件后，您可以使用任何默认主题（浅色/深色）或自定义主题。以下是如何在 main.jsx 或 main.tsx 中应用这些主题

转到 src 目录并在 main.jsx 或 main.tsx 中，将以下类名应用于根元素

light 适用于浅色主题。
dark 适用于深色主题。
text-foreground 设置文本颜色。
bg-background 设置背景颜色。

// main.tsx or main.jsx
import React from "react";
import ReactDOM from "react-dom/client";
import {NextUIProvider} from "@nextui-org/react";
import App from "./App";
import "./index.css";

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <NextUIProvider>
      <main className="dark text-foreground bg-background">
        <App />
      </main>
    </NextUIProvider>
  </React.StrictMode>,
);

注意：请参阅颜色部分以了解有关颜色类的更多信息。

默认插件选项

nextui 插件提供了一个默认结构。它概述如下

module.exports = {
  plugins: [
    nextui({
      prefix: "nextui", // prefix for themes variables
      addCommonColors: false, // override common colors (e.g. "blue", "green", "pink").
      defaultTheme: "light", // default theme from the themes object
      defaultExtendTheme: "light", // default theme to extend on custom themes
      layout: {}, // common layout tokens (applied to all themes)
      themes: {
        light: {
          layout: {}, // light theme layout tokens
          colors: {}, // light theme colors
        },
        dark: {
          layout: {}, // dark theme layout tokens
          colors: {}, // dark theme colors
        },
        // ... custom themes
      },
    }),
  ],
};

主题选项

这些是可用于将自定义配置应用于主题的选项。

module.exports = {
  plugins: [
    nextui({
      themes: {
        light: {
          layout: {},
          colors: {}
        },
        dark: {
          layout: {},
          colors: {}
        },
        ... // custom themes
      }
    })
  ]
}

嵌套主题

NextUI 支持嵌套主题，允许您将不同的主题应用到应用程序的不同部分

<html class="dark">
  ...
  <div class="light">...</div>
  <div class="purple-dark">...</div>
</html>

基于主题的变体

NextUI 允许您根据当前激活的主题应用 TailwindCSS 样式。以下是有关如何执行此操作的示例

<!-- In dark theme, background will be dark and text will be light. 
  In light theme, background will be light and text will be dark -->

<div class="dark dark:bg-gray-800 dark:text-white bg-white text-black">
  ...
  <div>Text color changes based on theme</div>
</div>

<div class="light light:bg-gray-100 light:text-black bg-black text-white">
  ...
  <div>Text color changes based on theme</div>
</div>

API 参考

下表概述了在 NextUI 中使用主题时可以使用各种属性

属性	类型	描述	默认值
prefix	`字符串`	css 变量的前缀。	`nextui`
addCommonColors	`布尔值`	如果为真，则常见的 nextui 颜色（例如“蓝色”、“绿色”、“紫色”）将替换 TailwindCSS 默认颜色。	`false`
defaultTheme	`light` \| `dark`	要使用的默认主题。	`light`
defaultExtendTheme	`light` \| `dark`	要扩展的默认主题。	`light`
layout	LayoutTheme	布局定义。	-
主题	ConfigThemes	主题定义。	-

类型

ConfigThemes

type ConfigTheme = {
  extend?: "light" | "dark"; // base theme to extend
  layout?: LayoutTheme; // see LayoutTheme
  colors?: ThemeColors; // see ThemeColors
};

type ConfigThemes = Record<string, ConfigTheme>;

LayoutTheme

type BaseThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
};

type FontThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
  tiny?: string;
};

interface LayoutTheme {
  /**
   * The default font size applied across the components.
   */
  fontSize?: FontThemeUnit;
  /**
   * The default line height applied across the components.
   */
  lineHeight?: FontThemeUnit;
  /**
   * The default radius applied across the components.
   * we recommend to use `rem` units.
   */
  radius?: BaseThemeUnit;
  /**
   * A number between 0 and 1 that is applied as opacity-[value] when
   * the component is disabled.
   */
  disabledOpacity?: string | number;
  /**
   * The default height applied to the divider component.
   * we recommend to use `px` units.
   */
  dividerWeight?: string;
  /**
   * The border width applied across the components.
   */
  borderWidth?: BaseThemeUnit;
  /**
   * The box shadow applied across the components.
   */
  boxShadow?: BaseThemeUnit;
}

ThemeColors

type ColorScale = {
  50: string;
  100: string;
  200: string;
  300: string;
  400: string;
  500: string;
  600: string;
  700: string;
  800: string;
  900: string;
  foreground: string; // contrast color
  DEFAULT: string;
};

type BaseColors = {
  background: ColorScale; // the page background color
  foreground: ColorScale; // the page text color
  divider: ColorScale; // used for divider and single line border
  overlay: ColorScale; // used for modal, popover, etc.
  focus: ColorScale; // used for focus state outline
  content1: ColorScale; // used for card, modal, popover, etc.
  content2: ColorScale;
  content3: ColorScale;
  content4: ColorScale;
};

// brand colors
type ThemeColors = BaseColors & {
  default: ColorScale;
  primary: ColorScale;
  secondary: ColorScale;
  success: ColorScale;
  warning: ColorScale;
  danger: ColorScale;
};