主題色彩

了解預設主題的調色盤以及如何自訂。

預設色彩 Token

Joy UI 的預設主題包含 5 個內建的語意化調色盤，具有淺色和深色對應，可協助您快速建立美觀的使用者介面。

已複製

Token	淺色	深色

全域變體 token

Joy UI 的主要功能之一是每個元件中都提供的四種全域變體。它們使用內建的色彩調色盤，格式為變體類型 | 狀態 | CSS 屬性。例如：

solidBg 指的是 solid 變體在初始狀態下的背景顏色。
outlinedHoverBorder 指的是 outlined 變體在 hover 狀態下的邊框顏色。

通道 token

通道 token 有助於使用 (rgba) 建立半透明顏色。以 Channel 結尾的 token 會針對每個調色盤自動產生。

lightChannel：從調色盤的 200 token 產生。
mainChannel：從調色盤的 500 token 產生。
darkChannel：從調色盤的 800 token 產生。

以下程式碼片段示範如何使用它們

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}>`.

變更全域變體 token

開始使用內建變體變更顏色外觀的一個好方法是使用 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 的項目。
- 我們可以透過三種主要的客製化方法之一來重新建立它。

新增顏色 token

若要讓任何新顏色可透過 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 介面以包含新的 token。

// 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;
  }
}

移除預設 token

若要移除任何預設 token，請在擴充主題中使用 undefined 作為值。這會將它們從 theme 物件中移除，並防止產生對應的 CSS 變數。

例如，所有預設全域變體色彩 token 都帶有 :active 虛擬類別的樣式。以下是如何從實色變體中移除它的方法。

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 開始編輯