Pigment CSS 入門

了解如何開始使用 Pigment CSS 自訂您的元件。

Pigment CSS 是一個零執行階段的 CSS-in-JS 函式庫，它在建置時預先編譯，使其與 React Server Components 相容，並為您提供比其他樣式引擎顯著的效能提升。

Pigment CSS 與任何 React 元件函式庫相容，並且可以與 Vite 和 Next.js 一起使用。

如果您有現有的 Material UI 專案，請查看遷移至 Pigment CSS 指南。

先決條件

Node.js
套件管理器
Next.js 或 Vite 專案

您可以使用以下命令快速追蹤您的 Pigment CSS 安裝和專案建立

手動安裝

若要開始在現有專案上使用，請使用以下命令安裝 Pigment CSS

接下來，前往您的設定檔並匯入 withPigment 外掛程式

最後，在您的 layout.tsx (Next.js) 或 main.tsx (Vite) 檔案中匯入 Pigment CSS 樣式表

import '@pigment-css/react/styles.css';

用法

Pigment CSS 滿足現代 React 開發的需求：它與 React Server Components 相容，並讓您享受 CSS-in-JS 的優點，而且完全沒有執行階段效能成本。

使用 Pigment CSS，您可以建立本地作用域的可重複使用樣式、主題、CSS 變數等等。

樣式設定

Pigment CSS 通過各種 API 簡化了樣式的建立和定義

css：用於可重複使用的樣式
globalCss：用於全域樣式
keyframes：用於可重複使用的動畫關鍵影格
styled：用於樣式化元件

建立可重複使用的樣式

使用 css API 建立可重複使用的樣式

import { css } from '@pigment-css/react';

您可以使用樣板語法或物件語法來執行此操作

樣板語法

const bodyBackground = css`
  background-color: #000;
  color: #fff;
`;

物件語法

const mainClass = css({
  display: '#000',
  color: '#fff',
});

建立全域樣式

使用 globalCss API 定義要跨整個應用程式載入的全域樣式。

您應該在 JavaScript 檔案的頂層定義這些樣式

import { globalCss } from '@pigment-css/react';

globalCss`
  body {
    margin: 0;
    padding: 0;
  }
`;

建立樣式化元件

將樣式作用域限定於元件可確保僅載入必要的 CSS，並帶來更好的模組化、可讀性和可維護性。您可以根據 props 或執行階段值將條件式樣式套用至您的元件。

使用 styled API 建立樣式化元件

import { styled } from '@pigment-css/react';

const Heading = styled('div')({
  fontSize: '2rem',
  color: '#9FADBC',
  fontWeight: 'bold',
  margin: '1rem',
});

根據 props 設定樣式

使用 variants 鍵根據 props 定義不同的樣式選項。當 prop 的值在建置時已知時，建議使用此方法。

每個 variants 都是一個具有 props 和 style 鍵的物件

import { styled } from '@pigment-css/react';

const Heading = styled('div')({
  fontSize: '2rem',
  color: '#9FADBC',
  fontWeight: 'bold',
  margin: '1rem',
  variants: [
    {
      props: { variant: 'success' },
      style: { color: '#23AD79' },
    },
    {
      props: { size: 'small' },
      style: { fontSize: '1.5rem' },
    },
  ],
});

根據執行階段值設定樣式

當 prop 的值事先未知時，您可以根據執行階段值設定元件的樣式

const Heading = styled('h1')({
  color: ({ isError }) => (isError ? 'red' : 'black'),
});

主題

Pigment CSS 支援主題化，以便在整個應用程式中套用一致的樣式和值。您可以通過在設定檔中定義主題來建立主題

import { withPigment } from '@pigment-css/nextjs-plugin';

export default withPigment(nextConfig, {
  theme: {
    colors: {
      primary: 'tomato',
      secondary: 'cyan',
    },
    spacing: {
      unit: 8,
    },
    typography: {
      fontFamily: 'Inter, sans-serif',
    },
    // ...more keys and values, it's free style!
  },
});

若要存取您的主題，請將回呼與 styled() 和 css() API 一起使用

const Heading = styled('h1')(({ theme }) => ({
  color: theme.colors.primary,
  fontSize: theme.spacing.unit * 4,
  fontFamily: theme.typography.fontFamily,
}));

CSS 變數支援

當主題值由 extendTheme 工具程式包裝時，Pigment CSS 會從主題值產生 CSS 變數，從而建立一個 vars 物件

import { withPigment, extendTheme } from '@pigment-css/nextjs-plugin';

export default withPigment(nextConfig, {
  theme: extendTheme({
    colors: {
      primary: 'tomato',
      secondary: 'cyan',
    },
    spacing: {
      unit: 8,
    },
    typography: {
      fontFamily: 'Inter, sans-serif',
    },
  }),
});

色彩配置

您可以使用 extendTheme 工具程式中的 colorSchemes 鍵來根據不同的條件指定不同的值，例如在深色模式和淺色模式之間切換

extendTheme({
  colorSchemes: {
    light: {
      colors: {
        background: '#f9f9f9',
        foreground: '#121212',
      },
    },
    dark: {
      colors: {
        background: '#212121',
        foreground: '#fff',
      },
    },
  },
});

Pigment CSS 預設使用 prefers-color-scheme 媒體查詢在色彩配置之間切換

const colorScheme = css`
  background-color: ${({ theme }) => theme.colorSchemes.dark.colors.background};
  color: ${({ theme }) => theme.colorSchemes.dark.colors.foreground};

  @media (prefers-color-scheme: light) {
    background-color: ${({ theme }) => theme.colorSchemes.light.colors.background};
    color: ${({ theme }) => theme.colorSchemes.light.colors.foreground};
  }
`;

您還可以通過提供 getSelector 函數來自訂行為

 extendTheme({
   colorSchemes: {
     light: { ... },
     dark: { ... },
   },
+  getSelector: (colorScheme) => colorScheme ? `.theme-${colorScheme}` : ':root',
 });

sx 屬性

Pigment CSS 包含 sx 屬性，可讓您為任何元素提供一次性的內聯自訂樣式。

在建置時，Pigment CSS 會將 sx 屬性替換為 className 和 style 屬性。sx 屬性適用於所有 Material UI 元件以及 HTML 元素和任何第三方 JSX 元件。

<div sx={{ display: 'flex', flexDirection: 'column' }}>

<AnyComponent sx={{ fontSize: 12, color: 'red' }} />;

如果您在 HTML 元素上使用 sx 屬性，則需要擴充 HTMLAttributes 介面

type Theme = {
  // your theme type
};

declare global {
  namespace React {
    interface HTMLAttributes<T> {
      sx?:
        | React.CSSProperties
        | ((theme: Theme) => React.CSSProperties)
        | ReadonlyArray<
            React.CSSProperties | ((theme: Theme) => React.CSSProperties)
          >;
    }
  }
}

執行階段主題

若要存取執行階段主題，請使用 useTheme Hook

import { useTheme } from '@mui/material-pigment-css';

function MyComponent() {
  const theme = useTheme();

  return (
    <div>
      {Object.entries(theme.vars.palette.primary).map(([key, value]) => (
        <div key={key} style={{ width: 40, height: 40, background: value }}>
          {key}: {value}
        </div>
      ))}
    </div>
  );
}