@blocklet/payment-react/docs/guides-theming.ja.md

Reusable react components for payment kit v2

# テーマ設定

組み込みのテーマプロバイダーとMaterial-UIのテーマオプションを使用して、支払いコンポーネントの外観をカスタマイズする方法を学びます。`@blocklet/payment-react`ライブラリはMaterial-UIを基盤に構築されており、支払いフローのルックアンドフィールを広範囲にわたって制御できます。

## `PaymentThemeProvider`の概要

このライブラリには、すべての支払いコンポーネントをラップする専用の`PaymentThemeProvider`が含まれています。このプロバイダーは、ArcBlock UXテーマ（`@arcblock/ux/lib/Theme`）から継承したデフォルトテーマを確立し、ArcBlockエコシステム内での視覚的な一貫性を保証します。また、特別な`chip`カラーパレットやさまざまなMUIコンポーネントのスタイルオーバーライドなど、独自のカスタマイズも追加します。

`PaymentThemeProvider`の構造を簡略化したものを以下に示します：

```tsx src/theme/index.tsx icon=logos:react
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`オブジェクトを受け入れ、カスタムスタイルを適用するための2つの主要な方法を提供します。

### 1. `styleOverrides`の使用

詳細な構造的変更を行うには、支払いコンポーネントのスコープ内で特定のMaterial-UIコンポーネントのスタイルをオーバーライドできます。これは、テーマ設定の標準的なMUIの方法です。

```tsx プライマリーボタンのカスタマイズ icon=logos:react
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from '@/hooks/session-context'; // Assuming session context is defined here

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>
  );
}
```

この例では、プライマリーのcontainedボタン（`MuiButton.styleOverrides.containedPrimary`）をターゲットにし、その背景色とテキスト色を変更しています。

### 2. `sx`プロパティの使用

手早く、特定のCSS変更を行うには、`theme`プロパティ内に`sx`オブジェクトを渡すことができます。これにより、CSSセレクターを使用してコンポーネント内の特定の要素をターゲットにできます。

```tsx sxプロパティでのカスタマイズ icon=logos:react
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`オブジェクトで拡張し、ステータスインジケーターのスタイルを設定します。これらの色はカスタムテーマでオーバーライドできます。

```ts src/theme/types.ts icon=mdi:language-typescript
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']`）モードの両方で定義されています。

以下に、ターゲットにできる主要な変数をいくつか示します：

```css src/theme/index.css icon=logos:css-3
: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`にあります。アプリケーションのタイポグラフィに合わせて、これらの設定をカスタムテーマでオーバーライドできます。

```ts src/theme/typography.ts icon=mdi:language-typescript
export const typography = {
  h1: {
    fontSize: '1.5rem',
    lineHeight: 1.2,
    fontWeight: 800,
  },
  body1: {
    fontSize: '0.875rem',
    lineHeight: 1.75,
  },
  // ... other typography settings
};
```

これらのカスタマイズのレイヤーを理解することで、支払いコンポーネントをアプリケーションに一貫性のある洗練されたデザインでシームレスに統合できます。

---

次に、データキャッシングや日付フォーマットなどのタスクに役立つさまざまなユーティリティ関数について見ていきましょう。

<x-card data-title="次へ: ユーティリティ" data-icon="lucide:wrench" data-href="/guides/utilities" data-cta="続きを読む">
  ライブラリが提供するユーティリティ関数のリファレンス。キャッシュされたリクエストや日付フォーマットなどが含まれます。
</x-card>