色板

色板使您能够修改组件的颜色以适应您的品牌。

颜色令牌

色板颜色由四个令牌表示

main: 颜色的主色调
light: 比 main 更浅的色调
dark: 比 main 更深的色调
contrastText: 文本颜色，旨在与 main 形成对比

以下是 Material UI 的默认主题如何定义 primary 颜色令牌

const primary = {
  main: '#1976d2',
  light: '#42a5f5',
  dark: '#1565c0',
  contrastText: '#fff',
};

有关 Material Design 颜色系统的详细信息，请参阅颜色文档。

默认颜色

主题公开以下默认色板颜色（可在 theme.palette.* 下访问）

primary - 用于主要界面元素。
secondary - 用于次要界面元素。
error - 用于用户应注意的元素。
warning - 用于潜在的危险操作或重要消息。
info - 用于突出显示中性信息。
success - 用于指示用户触发的操作已成功完成。

有关颜色使用和指南的详细信息，请参阅 Material Design 的颜色系统。

值

您可以使用主题浏览器浏览默认色板值，或者通过在此页面上打开开发者工具控制台 (window.theme.palette)。

Primary

palette.primary.light

#42a5f5

palette.primary.main

#1976d2

palette.primary.dark

#1565c0

Secondary

palette.secondary.light

#ba68c8

palette.secondary.main

#9c27b0

palette.secondary.dark

#7b1fa2

Error

palette.error.light

#ef5350

palette.error.main

#d32f2f

palette.error.dark

#c62828

Warning

palette.warning.light

#ff9800

palette.warning.main

#ed6c02

palette.warning.dark

#e65100

Info

palette.info.light

#03a9f4

palette.info.main

#0288d1

palette.info.dark

#01579b

Success

palette.success.light

#4caf50

palette.success.main

#2e7d32

palette.success.dark

#1b5e20

默认色板对 secondary 色板颜色使用以 A 为前缀的色调（A200 等），而其他色板颜色则使用未加前缀的色调。

自定义

您可以通过在主题中包含色板对象来覆盖默认色板值。如果提供任何

色板颜色对象，它们将替换默认对象。

这可以通过使用颜色对象或直接提供颜色来实现

使用颜色对象

自定义色板颜色最直接的方法是导入并应用一个或多个颜色对象，如下所示

import * as React from 'react';
import { createTheme, ThemeProvider } from '@mui/material/styles';
import { lime, purple } from '@mui/material/colors';
import Button from '@mui/material/Button';

const theme = createTheme({
  palette: {
    primary: lime,
    secondary: purple,
  },
});

export default function UsingColorObject() {
  return (
    <ThemeProvider theme={theme}>
      <Button variant="contained">Primary</Button>
      <Button variant="contained" color="secondary" sx={{ ml: 2 }}>
        Secondary
      </Button>
    </ThemeProvider>
  );
}

import * as React from 'react';
import { createTheme, ThemeProvider } from '@mui/material/styles';
import { lime, purple } from '@mui/material/colors';
import Button from '@mui/material/Button';

const theme = createTheme({
  palette: {
    primary: lime,
    secondary: purple,
  },
});

export default function UsingColorObject() {
  return (
    <ThemeProvider theme={theme}>
      <Button variant="contained">Primary</Button>
      <Button variant="contained" color="secondary" sx={{ ml: 2 }}>
        Secondary
      </Button>
    </ThemeProvider>
  );
}

按 Enter 键开始编辑

直接提供颜色

要直接修改每种颜色，请提供一个包含一个或多个颜色令牌的对象。只需要 main 令牌；light、dark 和 contrastText 是可选的，如果未提供，则会自动计算它们的值

import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  palette: {
    primary: {
      main: '#FF5733',
      // light: will be calculated from palette.primary.main,
      // dark: will be calculated from palette.primary.main,
      // contrastText: will be calculated to contrast with palette.primary.main
    },
    secondary: {
      main: '#E0C2FF',
      light: '#F5EBFF',
      // dark: will be calculated from palette.secondary.main,
      contrastText: '#47008F',
    },
  },
});

light

main

dark

light

main

dark

对比度阈值

contrastText 令牌是使用 contrastThreshold 值计算的，以最大程度地提高背景和文本之间的对比度。

较高的对比度阈值会增加背景颜色被认为是浅色的点，因此会给出深色的 contrastText。请注意，对比度阈值遵循非线性曲线，默认值为 3，表示最小对比度为 3:1。

默认对比度阈值3:1

较高对比度阈值4.5:1

色调偏移

light 和 dark 令牌是使用 tonalOffset 值计算的，以移动 main 颜色的亮度。较高的色调偏移值会使 light 令牌更浅，而 dark 令牌更深。

例如，色调偏移默认值 0.2 将亮度移动大约两个索引，因此如果 main 令牌是 blue[500]，则 light 令牌将是 blue[300]，而 dark 将是 blue[700]。

色调偏移值可以是 0 到 1 之间的数字（这将适用于 light 和 dark 令牌），也可以是指定了 light 和 dark 键的对象

默认色调偏移0.2

light

main

dark

较高色调偏移0.5

light

main

dark

非对称色调偏移{ light: 0.1, dark: 0.9 }

light

main

dark

自定义颜色

要添加自定义颜色，您必须手动提供令牌，或使用 augmentColor 实用程序生成它们

手动提供令牌

最直接的方法是手动定义所有令牌——main、light、dark 和 contrastText

import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  palette: {
    ochre: {
      main: '#E3D026',
      light: '#E9DB5D',
      dark: '#A29415',
      contrastText: '#242105',
    },
  },
});

light

main

dark

如果您需要操作颜色，@mui/material/styles 提供了一组实用程序来帮助您。以下示例使用 alpha() 和 getContrastRatio() 实用程序来定义使用不透明度的令牌

import { createTheme, alpha, getContrastRatio } from '@mui/material/styles';

const violetBase = '#7F00FF';
const violetMain = alpha(violetBase, 0.7);

const theme = createTheme({
  palette: {
    violet: {
      main: violetMain,
      light: alpha(violetBase, 0.5),
      dark: alpha(violetBase, 0.9),
      contrastText: getContrastRatio(violetMain, '#fff') > 4.5 ? '#fff' : '#111',
    },
  },
});

light

main

dark

使用 augmentColor 实用程序生成令牌

或者，您可以使用色板的 augmentColor 实用程序生成 light、dark 和 contrastText 令牌，这与用于默认色板颜色的函数相同。这需要在两个步骤中创建主题，并提供 main 令牌，其他令牌将基于该令牌

import { createTheme } from '@mui/material/styles';

let theme = createTheme({
  // Theme customization goes here as usual, including tonalOffset and/or
  // contrastThreshold as the augmentColor() function relies on these
});

theme = createTheme(theme, {
  // Custom colors created with augmentColor go here
  palette: {
    salmon: theme.palette.augmentColor({
      color: {
        main: '#FF5733',
      },
      name: 'salmon',
    }),
  },
});

light

main

dark

对比度阈值和色调偏移值将适用于使用此实用程序定义的颜色。

在组件中使用

添加自定义颜色后，您将能够在组件中使用它，就像使用默认色板颜色一样

<Button color="custom">

TypeScript

如果您正在使用 TypeScript，则需要对自定义颜色使用模块扩充。

要向色板添加自定义颜色，您必须将其添加到 Palette 和 PaletteOptions 接口

declare module '@mui/material/styles' {
  interface Palette {
    custom: Palette['primary'];
  }

  interface PaletteOptions {
    custom?: PaletteOptions['primary'];
  }
}

要将自定义颜色用于组件的 color 属性，您必须将其添加到组件的 PropsColorOverrides 接口。下面的示例展示了如何使用 Button 组件执行此操作

declare module '@mui/material/Button' {
  interface ButtonPropsColorOverrides {
    custom: true;
  }
}

添加颜色令牌

要添加新的颜色令牌，请将其包含在颜色的对象中，如下所示

import { createTheme } from '@mui/material/styles';
import { blue } from '@mui/material/colors';

const theme = createTheme({
  palette: {
    primary: {
      light: blue[300],
      main: blue[500],
      dark: blue[700],
      darker: blue[900],
    },
  },
});

light

main

dark

更深色

TypeScript

如果您正在使用 TypeScript，则需要使用模块扩充将新的颜色令牌添加到 PaletteColor 和 SimplePaletteColorOptions 接口，如下所示

declare module '@mui/material/styles' {
  interface PaletteColor {
    darker?: string;
  }

  interface SimplePaletteColorOptions {
    darker?: string;
  }
}

非色板颜色

要了解如何在 theme.palette 之外添加颜色，请参阅主题化——自定义变量。

可访问性

为了满足 WCAG 2.1 规则 1.4.3 中定义的至少 4.5:1 的最小对比度，请创建一个对比度阈值为 4.5 的自定义主题，如下所示

import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  palette: {
    contrastThreshold: 4.5,
  },
});

选择颜色

需要灵感？Material Design 团队构建了一个调色板配置工具来帮助您。

颜色方案

要添加内置的浅色和深色颜色方案，而无需创建单独的主题，请使用 colorSchemes: { light: true, dark: true }。这将为两种颜色方案生成默认令牌

import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  colorSchemes: {
    light: true,
    dark: true,
  },
});

要覆盖每种颜色方案的默认令牌，请使用如下所示的相同色板对象

const theme = createTheme({
  colorSchemes: {
    light: {
      palette: {
        primary: {
          main: '#FF5733',
        },
        // ...other tokens
      },
    },
    dark: {
      palette: {
        primary: {
          main: '#E0C2FF',
        },
        // ...other tokens
      },
    },
  },
});

colorSchemes API 是 palette API 的增强版本，并且是 Material UI v6 开始此目的的首选 API。如果您同时提供 colorSchemes 和 palette，则后者将覆盖前者中定义的任何样式。

const theme = createTheme({
  palette: {
    primary: {
      main: '...',
    },
  },
  colorSchemes: {
    light: {
      // This will be replaced by the palette defined above
      palette: {
        primary: {
          main: '...',
        },
      },
    },
    dark: { ... },
  },
});

暗黑模式

有关如何为主题设置暗黑模式的详细信息，请访问暗黑模式指南。