主题颜色

了解默认主题的调色板以及如何自定义它。

默认颜色令牌

Joy UI 的默认主题包含 5 个内置的语义颜色调色板，带有浅色和深色映射，以帮助您快速构建美观的 UI。

已复制

令牌	浅色	深色

全局变体令牌

Joy UI 的主要功能之一是在每个组件中都可用的四个全局变体。它们使用内置的调色板，遵循 变体类型 | 状态 | CSS 属性 的格式。例如

solidBg 指的是 solid 变体在其初始状态下的背景颜色。
outlinedHoverBorder 指的是 outlined 变体在其悬停状态下的边框颜色。

通道令牌

通道令牌有助于使用 (rgba) 创建半透明颜色。以 Channel 结尾的令牌是为每个调色板自动生成的。

lightChannel：从调色板的 200 令牌生成。
mainChannel：从调色板的 500 令牌生成。
darkChannel：从调色板的 800 令牌生成。

下面的代码片段展示了如何使用它们

import Typography from '@mui/joy/Typography';

<Typography
  sx={theme => ({
    color: `rgba(${theme.vars.palette.primary.mainChannel} / 0.72)`,
  })}
>

自定义

更改默认值

要在仍然遵循调色板模式的同时更改每种颜色的 HEX 代码，请通过访问目标模式（浅色或深色）上的 palette 节点来扩展主题

import { extendTheme } from '@mui/joy/styles';

const theme = extendTheme({
  colorSchemes: {
    dark: {
      palette: {
        primary: {
          50: '#C0CCD9',
          100: '#A5B8CF',
          200: '#6A96CA',
          300: '#4886D0',
          400: '#2178DD',
          500: '#096BDE',
          600: '#1B62B5',
          700: '#265995',
          800: '#2F4968',
          900: '#2F3C4C',
        },
      },
    },
  },
});

// Then, pass it to `<CssVarsProvider theme={theme}>`.

更改全局变体令牌

一个好的开始方法是使用 Button 组件作为起点，来更改内置变体的颜色外观。例如，以下是如何使 Joy UI Button 匹配另一个系统的颜色，例如 Bootstrap

Bootstrap 的默认按钮与 Joy UI 的 solid 变体相当。
Bootstrap 的 secondary 变体使用灰色，类似于 Joy UI 的 neutral。
Bootstrap 的 btn-light 类似于 Joy UI 的按钮，使用 soft 变体和 neutral 调色板。
Joy UI 的默认值不包括任何类似于 Bootstrap 的 btn-dark 的内容。
- 我们可以使用三种主要自定义方法之一来重新创建它。

添加颜色令牌

要使任何新颜色通过 color 属性可用，请将它们插入扩展主题的 colorSchemes 键中。您还可以使用 styled 和 sx API 访问它们。

extendTheme({
  colorSchemes: {
    light: {
      palette: {
        // `gradient` is a new color token
        gradient: {
          primary: 'linear-gradient(to top, var(--joy-palette-primary-main), #000)',
        },
      },
    },
  },
});

// `sx` prop usage example:
<Button sx={{ background: (theme) => theme.vars.palette.gradient.primary }} />;

TypeScript

当在 TypeScript 中工作时，扩充主题的 Palette 接口，以包含新的令牌。

// You can put this to any file that's included in your tsconfig
declare module '@mui/joy/styles' {
  interface Palette {
    gradient: {
      primary: string;
    };
  }
}

添加新的调色板

要添加全新的调色板，使用任何类型的比例，并使它们通过 color 属性可用，请将它们插入扩展主题的 colorSchemes 键中。

下面的代码片段将自定义的 secondary 调色板添加到主题中。

import { extendTheme } from '@mui/joy/styles';

const theme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        secondary: {
          // Credit:
          // https://github.com/tailwindlabs/tailwindcss/blob/master/src/public/colors.js
          50: '#fdf2f8',
          100: '#fce7f3',
          200: '#fbcfe8',
          300: '#f9a8d4',
          400: '#f472b6',
          500: '#ec4899',
          600: '#db2777',
          700: '#be185d',
          800: '#9d174d',
          900: '#831843',
          // Adjust the global variant tokens as you'd like.
          // The tokens should be the same for all color schemes.
          solidBg: 'var(--joy-palette-secondary-400)',
          solidActiveBg: 'var(--joy-palette-secondary-500)',
          outlinedBorder: 'var(--joy-palette-secondary-500)',
          outlinedColor: 'var(--joy-palette-secondary-700)',
          outlinedActiveBg: 'var(--joy-palette-secondary-100)',
          softColor: 'var(--joy-palette-secondary-800)',
          softBg: 'var(--joy-palette-secondary-200)',
          softActiveBg: 'var(--joy-palette-secondary-300)',
          plainColor: 'var(--joy-palette-secondary-700)',
          plainActiveBg: 'var(--joy-palette-secondary-100)',
        },
      },
    },
    dark: {
      palette: {
        secondary: {
          // Credit:
          // https://github.com/tailwindlabs/tailwindcss/blob/master/src/public/colors.js
          50: '#fdf2f8',
          100: '#fce7f3',
          200: '#fbcfe8',
          300: '#f9a8d4',
          400: '#f472b6',
          500: '#ec4899',
          600: '#db2777',
          700: '#be185d',
          800: '#9d174d',
          900: '#831843',
          // Adjust the global variant tokens as you'd like.
          // The tokens should be the same for all color schemes.
          solidBg: 'var(--joy-palette-secondary-400)',
          solidActiveBg: 'var(--joy-palette-secondary-500)',
          outlinedBorder: 'var(--joy-palette-secondary-700)',
          outlinedColor: 'var(--joy-palette-secondary-600)',
          outlinedActiveBg: 'var(--joy-palette-secondary-900)',
          softColor: 'var(--joy-palette-secondary-500)',
          softBg: 'var(--joy-palette-secondary-900)',
          softActiveBg: 'var(--joy-palette-secondary-800)',
          plainColor: 'var(--joy-palette-secondary-500)',
          plainActiveBg: 'var(--joy-palette-secondary-900)',
        },
      },
    },
  },
});

// Then, pass it to `<CssVarsProvider theme={theme}>`.

然后，您将能够在 Joy UI 组件上使用 secondary 颜色

<Button color="secondary">
<IconButton variant="outlined" color="secondary">
<Chip variant="soft" color="secondary">

TypeScript

在 TypeScript 中工作时，您必须扩充主题的接口以包含新的调色板。

// You can put this to any file that's included in your tsconfig
import type { PaletteRange } from '@mui/joy/styles';

declare module '@mui/joy/styles' {
  interface ColorPalettePropOverrides {
    // apply to all Joy UI components that support `color` prop
    secondary: true;
  }

  interface Palette {
    // this will make the node `secondary` configurable in `extendTheme`
    // and add `secondary` to the theme's palette.
    secondary: PaletteRange;
  }
}

删除默认令牌

要删除任何默认令牌，请在扩展主题中使用 undefined 作为值。这会将它们从 theme 对象中删除，并阻止生成相应的 CSS 变量。

例如，所有默认全局变体颜色令牌都带有用于 :active 伪类的样式。以下是如何从 solid 变体中删除它。

import * as React from 'react';
import { CssVarsProvider, extendTheme } from '@mui/joy/styles';
import Box from '@mui/joy/Box';
import Button from '@mui/joy/Button';

// ⚠️ If the value is `undefined`, it should be `undefined` for other color schemes as well.
const theme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        primary: {
          solidActiveBg: undefined,
        },
      },
    },
    dark: {
      palette: {
        primary: {
          solidActiveBg: undefined,
        },
      },
    },
  },
});

const useEnhancedEffect =
  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;

export default function RemoveActiveTokens() {
  // the `node` is used for attaching CSS variables to this demo, you might not need it in your application.
  const [node, setNode] = React.useState(null);
  useEnhancedEffect(() => {
    setNode(document.getElementById('remove-active-tokens-demo'));
  }, []);

  return (
    <CssVarsProvider theme={theme} colorSchemeNode={node || null}>
      <Box
        id="remove-active-tokens-demo"
        sx={{ display: 'flex', gap: 1, flexWrap: 'wrap' }}
      >
        <Button>Button</Button>
      </Box>
    </CssVarsProvider>
  );
}

import * as React from 'react';
import { CssVarsProvider, extendTheme } from '@mui/joy/styles';
import Box from '@mui/joy/Box';
import Button from '@mui/joy/Button';

// ⚠️ If the value is `undefined`, it should be `undefined` for other color schemes as well.
const theme = extendTheme({
  colorSchemes: {
    light: {
      palette: {
        primary: {
          solidActiveBg: undefined,
        },
      },
    },
    dark: {
      palette: {
        primary: {
          solidActiveBg: undefined,
        },
      },
    },
  },
});

const useEnhancedEffect =
  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;

export default function RemoveActiveTokens() {
  // the `node` is used for attaching CSS variables to this demo, you might not need it in your application.
  const [node, setNode] = React.useState(null);
  useEnhancedEffect(() => {
    setNode(document.getElementById('remove-active-tokens-demo'));
  }, []);

  return (
    <CssVarsProvider theme={theme} colorSchemeNode={node || null}>
      <Box
        id="remove-active-tokens-demo"
        sx={{ display: 'flex', gap: 1, flexWrap: 'wrap' }}
      >
        <Button>Button</Button>
      </Box>
    </CssVarsProvider>
  );
}

按 Enter 开始编辑