主題陰影

了解預設主題的陰影比例以及如何自訂。

預設 tokens

Joy UI 使用 T 恤尺寸 (sm, md, lg 等) 來定義陰影，用於 Card、Menu 等元件。這些 tokens 分組在 theme.shadow 節點中

自訂預設陰影

提供鍵值到 shadow 節點以覆寫預設陰影

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

const theme = extendTheme({
  shadow: {
    xs: '{CSS box-shadow}',
    sm: '{CSS box-shadow}',
    md: '{CSS box-shadow}',
    lg: '{CSS box-shadow}',
    xl: '{CSS box-shadow}',
  },
});

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

新增陰影

您可以新增任何自訂鍵到 shadow 節點

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

const theme = extendTheme({
  shadow: {
    subtle: '{CSS box-shadow}',
    strong: '{CSS box-shadow}',
  },
});

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

TypeScript

當在 TypeScript 中工作時，您需要使用新的鍵來擴充主題的 Shadow 介面

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

陰影環

陰影環可以針對淺色和深色配色方案進行配置。若要建立陰影環，請提供有效的 CSS box-shadow 值給 shadowRing 節點

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

const theme = extendTheme({
  colorSchemes: {
    light: {
      // This creates a 1px box-shadow.
      shadowRing: '0 0 0 1px rgba(0 0 0 / 0.1)',
    },
    dark: {
      shadowChannel: '0 0 0 1px rgba(255 255 255 / 0.1)',
    },
  },
});

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

陰影色彩

陰影的顏色來自名為 var(--joy-shadowChannel) 的主題 token。您可以針對淺色和深色配色方案自訂值

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

const theme = extendTheme({
  colorSchemes: {
    light: {
      shadowChannel: '12 12 12',
    },
    dark: {
      shadowChannel: '0 0 0',
    },
  },
});

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

自訂元素上的陰影

若要在特定實例上自訂陰影顏色或陰影環，請使用來自 theme.shadow.* 的原始值。

// ✅
<Button
  sx={(theme) => ({
    boxShadow: theme.shadow.md,
    '--joy-shadowChannel': theme.vars.palette.primary.mainChannel,
    '--joy-shadowRing': 'inset 0 -3px 0 rgba(0 0 0 / 0.24)',
  })}
>

// ❌ Both of these do not work
<Button
  sx={(theme) => ({
    boxShadow: 'md',
    '--joy-shadowChannel': theme.vars.palette.primary.mainChannel,
    '--joy-shadowRing': 'inset 0 -3px 0 rgba(0 0 0 / 0.24)',
  })}
>
<Button
  sx={(theme) => ({
    boxShadow: theme.vars.shadow.md,
    '--joy-shadowChannel': theme.vars.palette.primary.mainChannel,
    '--joy-shadowRing': 'inset 0 -3px 0 rgba(0 0 0 / 0.24)',
  })}
>

Token	值	淺色	深色
xs
sm
md
lg
xl