調色盤

調色盤讓您能夠修改元件的色彩，以符合您的品牌。

色彩符記

調色盤色彩由四種符記表示

main：色彩的主要色調
light：比 main 淺的色調
dark：比 main 深的色調
contrastText：文字顏色，旨在與 main 形成對比

以下說明 Material UI 的預設主題如何定義主要色彩符記

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

預設調色盤為次要調色盤色彩使用帶有 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: { ... },
  },
});

深色模式

如需瞭解如何為您的主題設定深色模式的詳細資訊，請前往深色模式指南。