主題化 | ArcBlock

了解如何使用內建的主題提供者和 Material-UI 主題選項來自訂支付元件的外觀。@blocklet/payment-react 函式庫建立在 Material-UI 之上，讓您對支付流程的外觀和風格有廣泛的控制權。

PaymentThemeProvider 概覽

該函式庫包含一個專用的 PaymentThemeProvider，它包裝了所有支付元件。此提供者建立了一個預設主題，該主題繼承自 ArcBlock UX 主題 (@arcblock/ux/lib/Theme)，確保在 ArcBlock 生態系統中的視覺一致性。它還添加了自己的自訂功能，例如特殊的 chip 調色盤和對各種 MUI 元件的樣式覆寫。

以下是 PaymentThemeProvider 結構的簡化視圖：

src/theme/index.tsx

import { createTheme, ThemeProvider } from '@mui/material/styles';
import { create as createBlockletTheme, deepmerge } from '@arcblock/ux/lib/Theme';

export function PaymentThemeProvider({ children, theme: customTheme = {} }) {
  const parentTheme = useTheme();

  const mergeTheme = useMemo(() => {
    // Start with the base blocklet theme
    const blockletTheme = parentTheme.themeName === 'ArcBlock' ? parentTheme : createBlockletTheme();

    // Merge our custom payment theme options
    let paymentThemeOptions = deepmerge(blockletTheme, {
      // Custom palette extensions, e.g., for chips
      palette: {
        chip: { /* ... */ },
      },
      // Custom component style overrides
      components: {
        MuiButton: { /* ... */ },
        MuiOutlinedInput: { /* ... */ },
        // ... other components
      },
    });

    // Merge any user-provided custom theme
    paymentThemeOptions = deepmerge(paymentThemeOptions, customTheme);

    return createTheme(paymentThemeOptions);
  }, [parentTheme, customTheme]);

  return (
    <ThemeProvider theme={mergeTheme}>
      <CssBaseline />
      {children}
    </ThemeProvider>
  );
}

自訂元件樣式

自 1.14.22 版本起，您可以透過傳遞 theme 屬性輕鬆地為單個支付元件自訂主題。此屬性接受一個 Material-UI ThemeOptions 物件，為您提供了兩種主要方式來應用自訂樣式。

1. 使用 styleOverrides

對於深層的、結構性的變更，您可以在支付元件的範圍內覆寫特定 Material-UI 元件的樣式。這是標準的 MUI 主題化方式。

Customizing the Primary Button

import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from '@/hooks/session-context'; // 假設 session context 在此定義

function CustomStyledCheckout() {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <CheckoutForm
        id="plink_xxx"
        onChange={console.info}
        theme={{
          components: {
            MuiButton: {
              styleOverrides: {
                containedPrimary: {
                  backgroundColor: '#1DC1C7',
                  color: '#fff',
                  '&:hover': {
                    backgroundColor: 'rgb(20, 135, 139)',
                  },
                },
              },
            },
          },
        }}
      />
    </PaymentProvider>
  );
}

在此範例中，我們鎖定主要包含按鈕 (MuiButton.styleOverrides.containedPrimary) 並更改其背景和文字顏色。

2. 使用 sx 屬性

對於快速、有針對性的 CSS 變更，您可以在 theme 屬性中傳遞一個 sx 物件。這允許您使用 CSS 選擇器來鎖定元件內的特定元素。

Customizing with the sx Prop

import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from '@/hooks/session-context';

function SxStyledCheckout() {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <CheckoutForm
        id="plink_xxx"
        showCheckoutSummary={false}
        onChange={console.info}
        theme={{
          sx: {
            // Target the submit button by its specific class name
            '.cko-submit-button': {
              backgroundColor: '#1DC1C7',
              color: '#fff',
              '&:hover': {
                backgroundColor: 'rgb(20, 135, 139)',
              },
            },
          },
        }}
      />
    </PaymentProvider>
  );
}

當您需要覆寫一個透過標準元件樣式覆寫不易存取的樣式時，此方法非常有用。

理解預設主題

預設主題建立在一套用於顏色、間距和排版的 CSS 變數（設計權杖）系統之上，允許在淺色和深色模式下實現一致的樣式。

調色盤

該主題擴展了標準的 Material-UI 調色盤，增加了一個自訂的 chip 物件來為狀態指示器設定樣式。您可以在您的自訂主題中覆寫這些顏色。

src/theme/types.ts

declare module '@mui/material/styles' {
  interface Palette {
    chip: {
      success: { text: string; background: string; border: string; };
      default: { text: string; background: string; border: string; };
      secondary: { text: string; background: string; border: string; };
      error: { text: string; background: string; border: string; };
      warning: { text: string; background: string; border: string; };
      info: { text: string; background: string; border: string; };
    };
  }
  // ... PaletteOptions definition
}

設計權杖（CSS 變數）

對於進階的全域自訂，您可以覆寫定義主題的 CSS 變數。這些變數為淺色（:root）和深色（[data-theme='dark']）模式都進行了定義。

以下是您可以鎖定的一些關鍵變數：

src/theme/index.css

:root {
  /* 淺色主題 */
  --backgrounds-bg-base: #ffffff;
  --backgrounds-bg-interactive: #3b82f6;
  --foregrounds-fg-base: #030712;
  --foregrounds-fg-interactive: #3b82f6;
  --stroke-border-base: #eff1f5;
  --radius-m: 0.5rem; /* 8px */
}

[data-theme='dark'] {
  /* 深色主題 */
  --backgrounds-bg-base: #1b1b1f;
  --backgrounds-bg-interactive: #60a5fa;
  --foregrounds-fg-base: #edeef0;
  --foregrounds-fg-interactive: #60a5fa;
  --stroke-border-base: #2e3035;
  --radius-m: 0.5rem;
}

在您的全域樣式表中覆寫這些變數，將會對所有 @blocklet/payment-react 元件應用變更。

排版

預設的排版設定可以在 src/theme/typography.ts 中找到。您可以在您的自訂主題中覆寫任何這些設定，以匹配您應用程式的排版。

src/theme/typography.ts

export const typography = {
  h1: {
    fontSize: '1.5rem',
    lineHeight: 1.2,
    fontWeight: 800,
  },
  body1: {
    fontSize: '0.875rem',
    lineHeight: 1.75,
  },
  // ... other typography settings
};

透過理解這些自訂層次，您可以將支付元件無縫整合到您的應用程式中，並實現一致且精緻的設計。

接下來，探索各種實用工具函式，這些函式可以幫助您處理資料快取和日期格式化等任務。

下一步：實用工具

該函式庫提供的實用工具函式參考，包括快取請求和日期格式化。