色彩反轉

Joy UI 組件可以反轉其色彩，以符合父組件的變體。

動機

Joy UI 的全域變體功能為 variant 屬性提供了一致的值集。但當相同的樣式同時應用於父組件和子組件時，這些變體有時會導致怪異之處。請查看下面的兩個示範卡片，了解事情可能會如何出錯

• 在左側，按鈕變體為 solid，而其父卡片為預設的 outlined，因此設計效果良好。
• 在右側，solid 變體同時應用於按鈕和卡片，打亂了設計的層次結構和對比。

Joy UI 的色彩反轉功能可防止這種情況發生，同時仍保留全域變體本身的層次意義。

總覽

當在父組件上啟用色彩反轉時，所有子組件都會反轉其樣式（無論其各自的顏色屬性如何），以符合父組件的背景。反轉的樣式保持了其對應全域變體的語意含義——在下面的範例中，即使按鈕已被反轉以與其容器形成對比，它仍然是 solid。如果您將按鈕的變體更改為 outlined，您會看到設計仍然有效；但嘗試從父卡片中移除 invertedColors 屬性，您會看到設計如何瓦解（因此，這個功能為何如此實用）

優點

• 色彩反轉大幅減少了樣式設定工作。它可以處理所有子組件上的所有視覺狀態（懸停、啟用和焦點）。
• 它使您的介面具有可擴展性。新增到該區域的新組件就能正常工作。
• 它適用於客戶端和伺服器端渲染。
• 它適用於淺色和深色模式。
• 它可以隨時停用，而不會影響組件的結構。
• 它是一個可選擇加入的功能。如果您不使用它，額外的 CSS 變數將不會包含在生產樣式表中。
• 某些子組件可以排除在色彩反轉之外，請參閱「跳過子組件的色彩反轉」章節。

權衡

• 如果父組件僅包含少數子組件，則生成的樣式表大小可能會比您個別自訂每個子組件時顯著更大。（這對整體效能來說可能無關緊要。）
• 它不適用於不支援 CSS 變數的瀏覽器。

使用方式

支援的組件

以下組件在與 solid 或 soft 變體結合應用時，接受 invertedColors 屬性

• Alert
• Card
• Drawer
• Modal Dialog
• Menu
• Sheet

例外情況

色彩反轉預設情況下不影響 Autocomplete、Menu 或 Tooltip 組件的彈出視窗插槽。若要啟用它，請使用 slotProps 在各自的子組件上將 disablePortal 設定為 "true"，如下所示

跳過子組件的反轉

當 invertedColors 應用於父組件時，您可以將 data-skip-inverted-colors 屬性新增至子組件，以防止該子組件被反轉。

將色彩反轉應用於任何父組件

import { applySolidInversion, applySoftInversion } from '@mui/joy/colorInversion';

如果您需要將色彩反轉應用於預設不支援的父組件，您可以使用 applySolidInversion 或 applySoftInversion 實用工具，將其新增至任何包含子組件的組件。（這就是支援的組件在套用 invertedColors 屬性時在背後使用的。）

以下範例展示如何將這些實用工具與 sx 屬性和 styled API 一起使用

使用 sx 屬性

<Box sx={[{ ...baseStyles }, applySolidInversion('neutral')]}>...</Box>

使用 styled API

const Parent = styled('div')([{ ...baseStyles }, applySolidInversion('neutral')]);

運作方式

色彩反轉使用 invertedColors 屬性或應用實用工具將 CSS 變數新增至組件。此功能不涉及 React Context。

<Sheet invertedColors variant="solid" color="neutral">

// The parent's style sheet
{
  // the values of these variables depends on the parent's variant and color.
  --variant-softColor: …;
  --variant-softBg: …;
  --variant-softHoverColor: …;
  --variant-softHoverBg: …;
  --variant-softActiveBg: …;
  … // other variants
  --joy-palette-text-primary: …;
  --joy-palette-text-secondary: …;
  --joy-palette-text-tertiary: …;
  --joy-palette-background-surface: …;
  … // other theme palette tokens
}

因此，子組件將使用這些 CSS 變數而不是主題

// The children style sheet
// The values of these variables are inherited from the parent.
{
  color: var(--joy-palette-text-primary);
  background: var(--joy-palette-background-surface);
  …
}

常見範例

頁首

頁尾

側邊導覽

行銷區塊